


	                Tcl Built-In Commands



_________________________________________________________________

NAME
     Tcl - Summary of Tcl language syntax.
_________________________________________________________________


DESCRIPTION
     The following rules define the syntax and semantics  of  the
     Tcl language:

     [1]  A Tcl script is a string containing one  or  more  com-
          mands.  Semi-colons and newlines are command separators
          unless quoted as described below.  Close  brackets  are
          command  terminators  during  command substitution (see
          below) unless quoted.

     [2]  A command is evaluated in two steps.   First,  the  Tcl
          interpreter  breaks the command into words and performs
          substitutions as described below.  These  substitutions
          are  performed  in  the same way for all commands.  The
          first word is used to locate  a  command  procedure  to
          carry  out  the  command,  then all of the words of the
          command are passed to the command procedure.  The  com-
          mand  procedure  is free to interpret each of its words
          in any way it likes, such as an integer, variable name,
          list,  or  Tcl  script.   Different  commands interpret
          their words differently.

     [3]  Words of a command are separated by white space (except
          for newlines, which are command separators).

     [4]  If the  first  character  of  a  word  is  double-quote
          (``"'')  then  the  word  is  terminated  by  the  next
          double-quote character.  If semi-colons,  close  brack-
          ets,  or  white  space  characters (including newlines)
          appear between the quotes  then  they  are  treated  as
          ordinary  characters and included in the word.  Command
          substitution, variable substitution, and backslash sub-
          stitution  are  performed on the characters between the
          quotes as described below.  The double-quotes  are  not
          retained as part of the word.

     [5]  If the first character of  a  word  is  an  open  brace
          (``{'')  then  the  word  is terminated by the matching
          close brace (``}'').  Braces nest within the word:  for
          each  additional open brace there must be an additional
          close brace (however, if an open brace or  close  brace
          within  the  word is quoted with a backslash then it is
          not counted in locating the matching close brace).   No
          substitutions  are  performed on the characters between
          the braces except for  backslash-newline  substitutions
          described  below,  nor  do semi-colons, newlines, close
          brackets, or white space receive any special  interpre-
          tation.   The  word will consist of exactly the charac-
          ters between the outer braces, not including the braces
          themselves.

     [6]  If a word contains an open  bracket  (``['')  then  Tcl
          performs  command  substitution.  To do this it invokes
          the Tcl interpreter recursively to process the  charac-
          ters  following  the open bracket as a Tcl script.  The
          script may contain any number of commands and  must  be
          terminated  by  a close bracket (``]'').  The result of
          the script (i.e. the result of  its  last  command)  is
          substituted  into the word in place of the brackets and
          all of the characters between them.  There may  be  any
          number of command substitutions in a single word.  Com-
          mand substitution is not performed on words enclosed in
          braces.

     [7]  If a word contains a dollar-sign (``$'') then Tcl  per-
          forms  variable  substitution:  the dollar-sign and the
          following characters are replaced in the  word  by  the
          value  of a variable.  Variable substition may take any
          of the following forms:

          $name          Name is the name of a  scalar  variable;
                         the  name is terminated by any character
                         that isn't a letter,  digit,  or  under-
                         score.

          $name(index)   Name gives the name of an array variable
                         and  index  gives the name of an element
                         within that array.   Name  must  contain
                         only  letters,  digits, and underscores.
                         Command substitutions, variable  substi-
                         tutions, and backslash substitutions are
                         performed on the characters of index.

          ${name}        Name is the name of a  scalar  variable.
                         It may contain any characters whatsoever
                         except for close braces.

     There may be any number of variable substitutions in a  sin-
     gle  word.   Variable substitution is not performed on words
     enclosed in braces.

     [8]  If a backslash  (``\'')  appears  within  a  word  then
          backslash  substitution occurs.  In all cases but those  |
          described below the backslash is dropped and  the  fol-  |
          lowing  character  is  treated as an ordinary character  |
          and included in the word.  This allows characters  such
          as  double  quotes, close brackets, and dollar signs to
          be included in words without  triggering  special  pro-
          cessing.   The  following  table  lists  the  backslash
          sequences that are handled specially,  along  with  the
          value that replaces each sequence.

          \a                                                            ||
                Audible alert (bell) (0x7).

          \b    Backspace (0x8).

          \f    Form feed (0xc).

          \n    Newline (0xa).

          \r    Carriage-return (0xd).

          \t    Tab (0x9).

          \v    Vertical tab (0xb).

          \<newline>whiteSpace
                A single space character replaces the  backslash,  |
                newline,  and  all white space after the newline.  |
                This backslash sequence is unique in that  it  is  |
                replaced  in  a separate pre-pass before the com-  |
                mand is actually parsed.  This means that it will  |
                be  replaced  even when it occurs between braces,  |
                and the resulting space will be treated as a word  |
                separator if it isn't in braces or quotes.

          \\    Backslash (``\'').

          \ooo  The digits ooo (one, two, or three of them)  give
                the octal value of the character.

          \xhh  The hexadecimal digits hh  give  the  hexadecimal  |
                value of the character.  Any number of digits may  |
                be present.

     Backslash substitution is not performed on words enclosed in
     braces, except for backslash-newline as described above.

     [9]  If a hash character (``#'') appears at  a  point  where
          Tcl  is expecting the first character of the first word
          of a command, then the hash character and  the  charac-
          ters  that  follow it, up through the next newline, are
          treated as a comment and ignored.  The comment  charac-
          ter only has significance when it appears at the begin-
          ning of a command.

     [10] Each character is processed exactly  once  by  the  Tcl
          interpreter as part of creating the words of a command.

          For example, if  variable  substition  occurs  then  no
          further  substitions  are performed on the value of the
          variable;  the value is inserted into the  word  verba-
          tim.   If  command  substitution occurs then the nested
          command is processed entirely by the recursive call  to
          the  Tcl  interpreter;  no  substitutions  are perfomed
          before making the recursive call and no additional sub-
          stitutions  are  performed  on the result of the nested
          script.

     [11] Substitutions do not affect the word  boundaries  of  a
          command.  For example, during variable substitution the
          entire value of the variable becomes part of  a  single
          word, even if the variable's value contains spaces.



Tcl                      Last change:                           4



_________________________________________________________________

NAME
     append - Append to variable

SYNOPSIS
     append varName value ?value value ...?
_________________________________________________________________


DESCRIPTION
     Append all of the value arguments to the  current  value  of
     variable  varName.   If varName doesn't exist, it is given a
     value equal to the concatenation of all the value arguments.
     This  command  provides  an  efficient  way to build up long
     variables incrementally.  For example, ``append  a  $b''  is
     much more efficient than ``set a $a$b'' if $a is long.


KEYWORDS
     append, variable


_________________________________________________________________

NAME
     array - Manipulate array variables

SYNOPSIS
     array option arrayName ?arg arg ...?
_________________________________________________________________


DESCRIPTION
     This command performs one of several operations on the vari-
     able  given  by arrayName.  ArrayName must be the name of an
     existing array variable.   The  option  argument  determines
     what  action  is  carried  out  by  the  command.  The legal
     options (which may be abbreviated) are:

     array anymore arrayName searchId
          Returns 1 if there are any more  elements  left  to  be
          processed  in  an  array search, 0 if all elements have
          already been returned.  SearchId indicates which search
          on  arrayName  to  check, and must have been the return
          value from a previous invocation of array  startsearch.
          This  option  is particularly useful if an array has an
          element with an empty name, since the return value from
          array nextelement won't indicate whether the search has
          been completed.

     array donesearch arrayName searchId
          This command terminates an array  search  and  destroys
          all  the  state  associated with that search.  SearchId
          indicates which search on  arrayName  to  destroy,  and
          must have been the return value from a previous invoca-
          tion of array startsearch.  Returns an empty string.

     array names arrayName
          Returns a list containing the names of all of the  ele-
          ments  in  the  array.  If there are no elements in the
          array then an empty string is returned.

     array nextelement arrayName searchId
          Returns the name of the next element in  arrayName,  or
          an  empty  string  if  all  elements  of arrayName have
          already been returned in  this  search.   The  searchId
          argument  identifies the search, and must have been the
          return value of an array startsearch command.  Warning:
          if  elements  are  added  to or deleted from the array,
          then all searches are automatically terminated just  as
          if  array  donesearch had been invoked; this will cause
          array  nextelement  operations  to   fail   for   those
          searches.

     array size arrayName
          Returns a decimal string giving the number of  elements
          in the array.

     array startsearch arrayName
          This command initializes an  element-by-element  search
          through the array given by arrayName, such that invoca-
          tions of the array nextelement command will return  the
          names  of  the  individual elements in the array.  When
          the search has been  completed,  the  array  donesearch
          command  should  be  invoked.   The  return  value is a
          search identifier that must be used in  array  nextele-
          ment  and array donesearch commands; it allows multiple
          searches to be underway  simultaneously  for  the  same
          array.


KEYWORDS
     array, element names, search


_________________________________________________________________

NAME
     break - Abort looping command

SYNOPSIS
     break
_________________________________________________________________


DESCRIPTION
     This command may be invoked only inside the body of a  loop-
     ing  command  such as for or foreach or while.  It returns a
     TCL_BREAK code to signal the innermost containing loop  com-
     mand to return immediately.


KEYWORDS
     abort, break, loop


_________________________________________________________________

NAME
     case - Evaluate one of several scripts, depending on a given
     value

SYNOPSIS
     case string ?in? patList body ?patList body ...?
     case string ?in? {patList body ?patList body ...?}
_________________________________________________________________


DESCRIPTION
     Note: the case command is obsolete and is supported only for
     backward  compatibility.  At some point in the future it may
     be removed entirely.  You  should  use  the  switch  command
     instead.

     The case command matches string against each of the  patList
     arguments  in order.  Each patList argument is a list of one
     or more patterns.  If any of these patterns  matches  string
     then  case  evaluates the following body argument by passing
     it recursively to the Tcl interpreter and returns the result
     of  that  evaluation.   Each  patList argument consists of a
     single pattern or list of patterns.  Each pattern  may  con-
     tain any of the wild-cards described under string match.  If
     a patList argument is default, the corresponding  body  will
     be  evaluated  if  no patList matches string.  If no patList
     argument matches string and no default is  given,  then  the
     case command returns an empty string.

     Two syntaxes are provided for the  patList  and  body  argu-
     ments.   The  first uses a separate argument for each of the
     patterns and commands; this form is convenient if  substitu-
     tions  are desired on some of the patterns or commands.  The
     second form places all of the patterns and commands together
     into  a  single argument; the argument must have proper list
     structure, with the elements of the list being the  patterns
     and  commands.   The  second form makes it easy to construct
     multi-line case commands, since the braces around the  whole
     list  make  it unnecessary to include a backslash at the end
     of each line.  Since the patList arguments are in braces  in
     the  second  form,  no command or variable substitutions are
     performed on them;  this makes the behavior  of  the  second
     form different than the first form in some cases.


KEYWORDS
     case, match, regular expression


_________________________________________________________________

NAME
     catch - Evaluate script and trap exceptional returns

SYNOPSIS
     catch script ?varName?
_________________________________________________________________


DESCRIPTION
     The catch command may be used to prevent errors from  abort-
     ing command interpretation.  Catch calls the Tcl interpreter
     recursively to execute script, and always returns  a  TCL_OK
     code,  regardless  of any errors that might occur while exe-
     cuting script.  The return value from  catch  is  a  decimal
     string giving the code returned by the Tcl interpreter after
     executing script.  This will be 0 (TCL_OK) if there were  no
     errors  in  script;  otherwise it will have a non-zero value
     corresponding to one of the exceptional  return  codes  (see
     tcl.h  for  the definitions of code values).  If the varName
     argument is given, then it gives the  name  of  a  variable;
     catch  will  set  the  variable  to the string returned from
     script (either a result or an error message).


KEYWORDS
     catch, error


_________________________________________________________________

NAME
     cd - Change working directory

SYNOPSIS
     cd ?dirName?
_________________________________________________________________


DESCRIPTION
     Change the current working directory to dirName, or  to  the
     home  directory  (as specified in the HOME environment vari-
     able) if dirName is not given.  If  dirName  starts  with  a
     tilde,   then  tilde-expansion  is  done  as  described  for
     Tcl_TildeSubst.  Returns an empty string.


KEYWORDS
     working directory


_________________________________________________________________

NAME
     close - Close an open file

SYNOPSIS
     close fileId
_________________________________________________________________


DESCRIPTION
     Closes the file given by fileId.  FileId must be the  return
     value  from a previous invocation of the open command; after
     this command, it should not  be  used  anymore.   If  fileId
     refers  to  a command pipeline instead of a file, then close
     waits for the children to complete.  The  normal  result  of
     this  command is an empty string, but errors are returned if
     there are problems in closing the file or waiting for  chil-
     dren to complete.


KEYWORDS
     close, file


_________________________________________________________________

NAME
     concat - Join lists together

SYNOPSIS
     concat ?arg arg ...?                                          |
_________________________________________________________________


DESCRIPTION
     This command treats each argument as a list and concatenates
     them  into  a  single  list.  It also eliminates leading and
     trailing spaces in the arg's and  adds  a  single  separator
     space  between  arg's.   It permits any number of arguments.
     For example, the command

          concat a b {c d e} {f {g h}}
     will return

          a b c d e f {g h}
     as its result.

     If no args are supplied, the result is an empty string.       |


KEYWORDS
     concatenate, join, lists


_________________________________________________________________

NAME
     continue - Skip to the next iteration of a loop

SYNOPSIS
     continue
_________________________________________________________________


DESCRIPTION
     This command may be invoked only inside the body of a  loop-
     ing  command  such as for or foreach or while.  It returns a
     TCL_CONTINUE code to signal the  innermost  containing  loop
     command  to  skip  the remainder of the loop's body but con-
     tinue with the next iteration of the loop.


KEYWORDS
     continue, iteration, loop


_________________________________________________________________

NAME
     eof - Check for end-of-file condition on open file

SYNOPSIS
     eof fileId
_________________________________________________________________


DESCRIPTION
     Returns 1  if  an  end-of-file  condition  has  occurred  on
     fileId, 0 otherwise.  FileId must have been the return value
     from a previous call to open, or it may be stdin, stdout, or
     stderr to refer to one of the standard I/O channels.


KEYWORDS
     end, file


_________________________________________________________________

NAME
     error - Generate an error

SYNOPSIS
     error message ?info? ?code?
_________________________________________________________________


DESCRIPTION
     Returns a TCL_ERROR code, which causes  command  interpreta-
     tion to be unwound.  Message is a string that is returned to
     the application to indicate what went wrong.

     If the info argument is provided and  is  non-empty,  it  is
     used to initialize the global variable errorInfo.  errorInfo
     is used to accumulate a stack trace of what was in  progress
     when  an  error occurred; as nested commands unwind, the Tcl
     interpreter adds information  to  errorInfo.   If  the  info
     argument  is present, it is used to initialize errorInfo and
     the first increment of unwind information will not be  added
     by  the  Tcl  interpreter.  In other words, the command con-
     taining the error command will not appear in  errorInfo;  in
     its place will be info.  This feature is most useful in con-
     junction with the catch command: if a caught error cannot be
     handled  successfully,  info  can  be used to return a stack
     trace reflecting the original point  of  occurrence  of  the
     error:

          catch {...} errMsg
          set savedInfo $errorInfo
          ...
          error $errMsg $savedInfo

     If the code argument is present, then its value is stored in
     the errorCode global variable.  This variable is intended to
     hold a machine-readable description of the  error  in  cases
     where  such information is available; see the section BUILT-
     IN VARIABLES below for information on the proper format  for
     the  variable.   If  the  code argument is not present, then
     errorCode is automatically reset  to  ``NONE''  by  the  Tcl
     interpreter as part of processing the error generated by the
     command.


KEYWORDS
     error, errorCode, errorInfo


_________________________________________________________________

NAME
     eval - Evaluate a Tcl script

SYNOPSIS
     eval arg ?arg ...?
_________________________________________________________________


DESCRIPTION
     Eval takes one or more arguments, which together comprise  a
     Tcl  script containing one or more commands.  Eval concaten-
     ates all its arguments in the same  fashion  as  the  concat
     command,  passes  the  concatenated string to the Tcl inter-
     preter recursively, and returns the result of  that  evalua-
     tion (or any error generated by it).


KEYWORDS
     concatenate, evaluate, script


_________________________________________________________________

NAME
     exec - Invoke subprocess(es)

SYNOPSIS
     exec ?switches? arg ?arg ...?
_________________________________________________________________


DESCRIPTION
     This command treats its arguments as  the  specification  of
     one or more subprocesses to execute.  The arguments take the
     form of a standard shell pipeline where each arg becomes one
     word  of a command, and each distinct command becomes a sub-
     process.

     If the initial arguments to exec start with - then they  are  |
     treated  as  command-line  switches  and are not part of the  |
     pipeline  specification.    The   following   switches   are  |
     currently supported:                                          |

     -keepnew-  |
                  line                                                       ||
                  Retains a trailing newline  in  the  pipeline's  |
                  output.   Normally  a  trailing newline will be  |
                  deleted.                                         |

     --                                                                 ||
                  Marks  the  end of switches.  The argument fol-  |
                  lowing this one will be treated  as  the  first  |
                  arg even if it starts with a -.

     If an arg (or pair of arg's) has one of the forms  described
     below  then  it is used by exec to control the flow of input
     and output among the subprocess(es).   Such  arguments  will
     not  be  passed to the subprocess(es).  In forms such as ``<  |
     fileName'' fileName may either be  in  a  separate  argument  |
     from ``<'' or in the same argument with no intervening space  |
     (i.e. ``<fileName'').

     |              Separates distinct commands in the  pipeline.
                    The  standard output of the preceding command
                    will be piped into the standard input of  the
                    next command.

     |&             Separates distinct commands in the  pipeline.
                    Both  standard  output  and standard error of
                    the preceding command will be piped into  the
                    standard  input  of  the  next command.  This
                    form of redirection overrides forms  such  as
                    2> and >&.

     < fileName     The file named by fileName is opened and used
                    as  the  standard input for the first command
                    in the pipeline.

     <@ fileId      FileId must be the  identifier  for  an  open  |
                    file,  such as the return value from a previ-  |
                    ous call to open.  It is used as the standard  |
                    input  for the first command in the pipeline.  |
                    FileId must have been opened for reading.

     << value       Value is passed to the first command  as  its
                    standard input.

     > fileName     Standard output  from  the  last  command  is
                    redirected   to   the  file  named  fileName,
                    overwriting its previous contents.

     2> fileName    Standard error from all commands in the pipe-  |
                    line   is   redirected   to  the  file  named  |
                    fileName, overwriting its previous contents.   |

     >& fileName                                                        ||
                    Both  standard  output  from the last command  |
                    and standard  error  from  all  commands  are  |
                    redirected   to   the  file  named  fileName,  |
                    overwriting its previous contents.

     >> fileName    Standard output  from  the  last  command  is
                    redirected   to   the  file  named  fileName,
                    appending to it rather than overwriting it.

     2>> fileName   Standard error from all commands in the pipe-  |
                    line   is   redirected   to  the  file  named  |
                    fileName,  appending  to   it   rather   than  |
                    overwriting it.                                |

     >>& fileName                                                       ||
                    Both  standard  output  from the last command  |
                    and standard  error  from  all  commands  are  |
                    redirected   to   the  file  named  fileName,  |
                    appending to it rather than overwriting it.    |

     >@ fileId                                                          ||
                    FileId  must  be  the  identifier for an open  |
                    file, such as the return value from a  previ-  |
                    ous  call  to open.  Standard output from the  |
                    last command is redirected to fileId's  file,  |
                    which must have been opened for writing.       |

     2>@ fileId                                                         ||
                    FileId  must  be  the  identifier for an open  |
                    file,  such  as  the  return  value  from   a  |
                    previous  call  to open.  Standard error from  |
                    all commands in the pipeline is redirected to  |
                    fileId's  file.   The  file  must  have  been  |
                    opened for writing.                            |

     >&@ fileId                                                         ||
                    FileId  must  be  the  identifier for an open  |
                    file, such as the return value from a  previ-  |
                    ous  call to open.  Both standard output from  |
                    the last command and standard error from  all  |
                    commands  are  redirected  to  fileId's file.  |
                    The file must have been opened for writing.

     If standard output has not been  redirected  then  the  exec
     command returns the standard output from the last command in
     the pipeline.  If any of the commands in the  pipeline  exit
     abnormally or are killed or suspended, then exec will return
     an error and the error message will include  the  pipeline's
     output  followed  by  error messages describing the abnormal
     terminations; the errorCode variable will contain additional
     information about the last abnormal termination encountered.
     If any of the commands writes to its standard error file and
     that  standard error isn't redirected, then exec will return
     an error;  the error message  will  include  the  pipeline's
     standard  output, followed by messages about abnormal termi-
     nations (if any), followed by the standard error output.

     If the last character of the result or error  message  is  a
     newline  then  that  character  is normally deleted from the
     result or error message.  This is consistent with other  Tcl
     return values, which don't normally end with newlines.  How-  |
     ever, if -keepnewline is specified then the trailing newline  |
     is retained.

     If standard input isn't redirected with ``<'' or  ``<<''  or
     ``<@''  then the standard input for the first command in the
     pipeline is taken from the  application's  current  standard
     input.

     If the last arg is ``&'' then the pipeline will be  executed
     in  background.  In this case the exec command will return a  |
     list whose elements are the process identifiers for  all  of  |
     the  subprocesses in the pipeline.  The standard output from
     the  last  command  in  the  pipeline   will   go   to   the
     application's  standard output if it hasn't been redirected,
     and error output from all of the commands  in  the  pipeline
     will  go  to  the  application's  standard error file unless
     redirected.

     The first word in each command is taken as the command name;
     tilde-substitution  is  performed  on  it, and if the result
     contains  no  slashes  then  the  directories  in  the  PATH
     environment  variable  are searched for an executable by the
     given name.  If the name contains a slash then it must refer
     to  an  executable reachable from the current directory.  No
     ``glob'' expansion or  other  shell-like  substitutions  are
     performed on the arguments to commands.


KEYWORDS
     execute, pipeline, redirection, subprocess


_________________________________________________________________

NAME
     exit - End the application

SYNOPSIS
     exit ?returnCode?
_________________________________________________________________


DESCRIPTION
     Terminate the process, returning returnCode to the system as
     the  exit  status.   If  returnCode  isn't specified then it
     defaults to 0.


KEYWORDS
     exit, process


_________________________________________________________________

NAME
     expr - Evalue an expression

SYNOPSIS
     expr arg ?arg arg ...?
_________________________________________________________________


DESCRIPTION
     Concatenates arg's (adding separator spaces  between  them),  |
     evaluates  the  result  as a Tcl expression, and returns the  |
     value.  The operators permitted in  Tcl  expressions  are  a
     subset of the operators permitted in C expressions, and they
     have the same meaning and precedence as the corresponding  C
     operators.   Expressions almost always yield numeric results
     (integer  or  floating-point  values).   For  example,   the
     expression

          expr 8.2 + 6
     evaluates to 14.2.  Tcl expressions differ  from  C  expres-
     sions  in  the  way  that operands are specified.  Also, Tcl
     expressions support non-numeric  operands  and  string  com-
     parisons.

OPERANDS
     A Tcl expression consists  of  a  combination  of  operands,
     operators, and parentheses.  White space may be used between
     the operands and operators and parentheses; it is ignored by
     the  expression  processor.   Where  possible,  operands are
     interpreted as integer values.  Integer values may be speci-
     fied  in  decimal  (the normal case), in octal (if the first
     character of the operand is 0), or in  hexadecimal  (if  the
     first  two characters of the operand are 0x).  If an operand
     does not have one of the integer formats given  above,  then
     it  is  treated as a floating-point number if that is possi-
     ble.  Floating-point numbers may be specified in any of  the
     ways  accepted  by an ANSI-compliant C compiler (except that
     the ``f'', ``F'', ``l'', and ``L'' suffixes will not be per-
     mitted in most installations).  For example, all of the fol-
     lowing are valid  floating-point  numbers:   2.1,  3.,  6e4,
     7.91e+16.  If no numeric interpretation is possible, then an
     operand is left as a string  (and  only  a  limited  set  of
     operators may be applied to it).

     Operands may be specified in any of the following ways:

     [1]  As an numeric value, either integer or floating-point.

     [2]  As a Tcl variable,  using  standard  $  notation.   The
          variable's value will be used as the operand.

     [3]  As a string enclosed in double-quotes.  The  expression
          parser  will  perform  backslash, variable, and command
          substitutions on the information  between  the  quotes,
          and use the resulting value as the operand

     [4]  As a string enclosed in braces.  The characters between
          the open brace and matching close brace will be used as
          the operand without any substitutions.

     [5]  As a Tcl command enclosed  in  brackets.   The  command
          will  be  executed  and  its result will be used as the
          operand.

     [6]  As a mathematical function whose arguments have any  of  |
          the above forms for operands, such as ``sin($x)''.  See  |
          below for a list of defined functions.

     Where  substitutions  occur  above   (e.g.   inside   quoted
     strings),  they  are  performed by the expression processor.
     However, an additional layer  of  substitution  may  already
     have been performed by the command parser before the expres-
     sion processor was called.  As discussed below, it  is  usu-
     ally  best  to  enclose expressions in braces to prevent the
     command parser from performing  substitutions  on  the  con-
     tents.

     For some examples of simple expressions, suppose  the  vari-
     able  a  has the value 3 and the variable b has the value 6.
     Then the command on the left side of each of the lines below
     will produce the value on the right side of the line:

          expr 3.1 + $a           6.1
          expr 2 + "$a.$b"        5.6
          expr 4*[llength "6 2"]  8
          expr {{word one} < "word $a"}0

OPERATORS
     The valid operators are listed below, grouped in  decreasing
     order of precedence:

     -  ~  !             Unary minus, bit-wise NOT, logical  NOT.
                         None of these operands may be applied to
                         string operands, and bit-wise NOT may be
                         applied only to integers.

     *  /  %             Multiply, divide,  remainder.   None  of
                         these  operands may be applied to string
                         operands, and remainder may  be  applied
                         only  to  integers.   The remainder will  |
                         always have the same sign as the divisor  |
                         and  an  absolute value smaller than the  |
                         divisor.

     +  -                Add and subtract.  Valid for any numeric
                         operands.

     <<  >>              Left and right shift.  Valid for integer
                         operands only.

     <  >  <=  >=        Boolean  less,  greater,  less  than  or
                         equal,  and greater than or equal.  Each
                         operator produces 1 if the condition  is
                         true,  0 otherwise.  These operators may
                         be applied to strings as well as numeric
                         operands,  in  which  case  string  com-
                         parison is used.

     ==  !=              Boolean  equal  and  not  equal.    Each
                         operator  produces  a  zero/one  result.
                         Valid for all operand types.

     &                   Bit-wise   AND.    Valid   for   integer
                         operands only.

     ^                   Bit-wise  exclusive   OR.    Valid   for
                         integer operands only.

     |                   Bit-wise OR.  Valid for integer operands
                         only.

     &&                  Logical AND.  Produces  a  1  result  if
                         both operands are non-zero, 0 otherwise.
                         Valid   for   numeric   operands    only
                         (integers or floating-point).

     ||                  Logical OR.  Produces a 0 result if both
                         operands  are  zero, 1 otherwise.  Valid
                         for numeric operands only  (integers  or
                         floating-point).

     x?y:z               If-then-else, as in C.  If  x  evaluates
                         to  non-zero,  then  the  result  is the
                         value of y.  Otherwise the result is the
                         value  of  z.  The x operand must have a
                         numeric value.

     See the C manual for more details on the results produced by
     each  operator.   All of the binary operators group left-to-
     right within the same precedence level.   For  example,  the
     command

          expr 4*2 < 7
     returns 0.

     The &&, ||, and ?: operators have ``lazy evaluation'',  just
     as in C, which means that operands are not evaluated if they
     are not needed to determine the outcome.   For  example,  in
     the command

          expr {$v ? [a] : [b]}
     only one of [a] or [b] will actually be evaluated, depending
     on  the  value of $v.  Note, however, that this is only true
     if the entire expression is enclosed in  braces;   otherwise
     the  Tcl parser will evaluate both [a] and [b] before invok-
     ing the expr command.

MATH FUNCTIONS
     Tcl supports the following mathematical functions in expres-  |
     sions:                                                        |

          acos        cos         hypot      sinh                  |
          asin        cosh        log        sqrt                  |
          atan        exp         log10      tan                   |
          atan2       floor       pow        tanh                  |
          ceil        fmod        sin                              |
     Each of these functions invokes the math library function of  |
     the same name;  see the manual entries for the library func-  |
     tions for details on what they do.  Tcl also implements  the  |
     following  functions  for  conversion  between  integers and  |
     floating-point numbers:                                       |

     abs(arg)                                                           ||
          Returns  the  absolute value of arg.  Arg may be either  |
          integer or floating-point, and the result  is  returned  |
          in the same form.                                        |

     double(arg)                                                        ||
          If arg is a floating value, returns arg, otherwise con-  |
          verts arg to floating and returns the converted value.   |

     int(arg)                                                           ||
          If arg is an integer value, returns arg, otherwise con-  |
          verts arg to integer by truncation and returns the con-  |
          verted value.                                            |

     round(arg)                                                         ||
          If arg is an integer value, returns arg, otherwise con-  |
          verts arg to integer by rounding and returns  the  con-  |
          verted value.                                            |

     In addition to these predifined functions, applications  may  |
     define additional functions using Tcl_CreateMathFunc().

TYPES, OVERFLOW, AND PRECISION
     All internal computations involving integers are  done  with
     the  C  type  long,  and all internal computations involving
     floating-point are done with the C type double.   When  con-
     verting  a  string  to  floating-point, exponent overflow is
     detected and results in a  Tcl  error.   For  conversion  to
     integer  from  string,  detection of overflow depends on the
     behavior of some routines in the  local  C  library,  so  it
     should  be  regarded  as  unreliable.   In any case, integer
     overflow and underflow are generally not  detected  reliably
     for   intermediate  results.   Floating-point  overflow  and
     underflow are  detected  to  the  degree  supported  by  the
     hardware, which is generally pretty reliable.

     Conversion  among  internal  representations  for   integer,
     floating-point, and string operands is done automatically as
     needed.  For  arithmetic  computations,  integers  are  used
     until  some floating-point number is introduced, after which
     floating-point is used.  For example,

          expr 5 / 4
     returns 1, while

          expr 5 / 4.0
          expr 5 / ( [string length "abcd"] + 0.0 )
     both return 1.25.  Floating-point values are always returned  |
     with  a  ``.''  or  an ``e'' so that they will not look like  |
     integer values.  For example,                                 |

          expr 20.0/5.0                                            |
     returns   ``4.0'',   not   ``4''.    The   global   variable  |
     tcl_precision  determines  the  the  number  of  significant  |
     digits that are retained when floating values are  converted  |
     to  strings  (except  that trailing zeroes are omitted).  If  |
     tcl_precision is unset then 6 digits of precision are  used.  |
     To  retain  all of the significant bits of an IEEE floating-  |
     point number set tcl_precision to 17;  if a  value  is  con-  |
     verted  to  string with 17 digits of precision and then con-  |
     verted back  to  binary  for  some  later  calculation,  the  |
     resulting  binary value is guaranteed to be identical to the  |
     original one.


STRING OPERATIONS
     String values may be used  as  operands  of  the  comparison
     operators,  although  the  expression  evaluator tries to do
     comparisons as integer or floating-point when  it  can.   If
     one  of  the  operands  of  a comparison is a string and the
     other has a numeric value, the numeric operand is  converted
     back to a string using the C sprintf format specifier %d for
     integers and %g for floating-point values.  For example, the
     commands

          expr {"0x03" > "2"}
          expr {"0y" < "0x12"}
     both return 1.  The first comparison is done  using  integer
     comparison,  and  the second is done using string comparison
     after the second operand is converted to the string ``18''.


KEYWORDS
     arithmetic, boolean, compare, expression


_________________________________________________________________

NAME
     file - Manipulate file names and attributes

SYNOPSIS
     file option name ?arg arg ...?
_________________________________________________________________


DESCRIPTION
     This command provides several operations on a file's name or
     attributes.  Name is the name of a file; if it starts with a
     tilde, then tilde substitution is done before executing  the
     command   (see  the  manual  entry  for  Tcl_TildeSubst  for
     details).  Option indicates what to do with the  file  name.
     Any unique abbreviation for option is acceptable.  The valid
     options are:

     file atime name
          Returns a decimal string giving the time at which  file
          name  was  last  accessed.  The time is measured in the
          standard POSIX fashion as seconds from a fixed starting
          time  (often  January  1,  1970).   If the file doesn't
          exist or its access time  cannot  be  queried  then  an
          error is generated.

     file dirname name
          Returns all of the characters in name  up  to  but  not
          including  the  last  slash character.  If there are no
          slashes in name then returns ``.''.  If the last  slash
          in name is its first character, then return ``/''.

     file executable name
          Returns 1 if file name is  executable  by  the  current
          user, 0 otherwise.

     file exists name
          Returns 1 if file name exists and the current user  has
          search  privileges for the directories leading to it, 0
          otherwise.

     file extension name
          Returns all of the characters in name after and includ-
          ing  the  last dot in name.  If there is no dot in name
          then returns the empty string.

     file isdirectory name
          Returns 1 if file name is a directory, 0 otherwise.

     file isfile name
          Returns 1 if file name is a regular file, 0 otherwise.

     file lstat name varName
          Same as stat option (see below) except uses  the  lstat
          kernel  call  instead of stat.  This means that if name
          refers to a symbolic link the information  returned  in
          varName  is for the link rather than the file it refers
          to.  On systems that don't support symbolic links  this
          option behaves exactly the same as the stat option.

     file mtime name
          Returns a decimal string giving the time at which  file
          name  was  last  modified.  The time is measured in the
          standard POSIX fashion as seconds from a fixed starting
          time  (often  January  1,  1970).   If the file doesn't
          exist or its modified time cannot be  queried  then  an
          error is generated.

     file owned name
          Returns 1 if file name is owned by the current user,  0
          otherwise.

     file readable name
          Returns 1 if file name is readable by the current user,
          0 otherwise.

     file readlink name
          Returns the value of the symbolic link  given  by  name
          (i.e.  the  name  of  the  file it points to).  If name
          isn't a symbolic link or its value cannot be read, then
          an  error  is  returned.  On systems that don't support
          symbolic links this option is undefined.

     file rootname name
          Returns all of the characters in name  up  to  but  not
          including  the  last  ``.''  character in the name.  If
          name doesn't contain a dot, then returns name.

     file size name
          Returns a decimal string giving the size of  file  name
          in bytes.  If the file doesn't exist or its size cannot
          be queried then an error is generated.

     file stat  name varName
          Invokes the stat kernel call  on  name,  and  uses  the
          variable  given by varName to hold information returned
          from the kernel call.  VarName is treated as  an  array
          variable,  and  the following elements of that variable
          are set: atime, ctime,  dev,  gid,  ino,  mode,  mtime,
          nlink,  size, type, uid.  Each element except type is a
          decimal string with  the  value  of  the  corresponding
          field  from  the  stat return structure; see the manual
          entry for stat for  details  on  the  meanings  of  the
          values.  The type element gives the type of the file in
          the same form returned by the command file type.   This
          command returns an empty string.

     file tail name
          Returns all of the characters in name  after  the  last
          slash.  If name contains no slashes then returns name.

     file type name
          Returns a string giving the type of  file  name,  which
          will  be  one  of  file,  directory,  characterSpecial,
          blockSpecial, fifo, link, or socket.

     file writable name
          Returns 1 if file name is writable by the current user,
          0 otherwise.


KEYWORDS
     attributes, directory, file, name, stat


_________________________________________________________________

NAME
     flush - Flush buffered output for a file

SYNOPSIS
     flush fileId
_________________________________________________________________


DESCRIPTION
     Flushes any  output  that  has  been  buffered  for  fileId.
     FileId  must have been the return value from a previous call
     to open, or it may be stdout or stderr to access one of  the
     standard  I/O  streams;  it  must  refer  to a file that was
     opened for writing.  The command returns an empty string.


KEYWORDS
     buffer, file, flush, output


_________________________________________________________________

NAME
     for - ``For'' loop

SYNOPSIS
     for start test next body
_________________________________________________________________


DESCRIPTION
     For is a looping command, similar in structure to the C  for
     statement.   The start, next, and body arguments must be Tcl
     command strings, and test is an expression string.  The  for
     command  first invokes the Tcl interpreter to execute start.
     Then it repeatedly evaluates test as an expression;  if  the
     result  is  non-zero it invokes the Tcl interpreter on body,
     then invokes the Tcl interpreter on next, then  repeats  the
     loop.   The command terminates when test evaluates to 0.  If
     a continue command is invoked within body then any remaining
     commands  in the current execution of body are skipped; pro-
     cessing continues by invoking the Tcl interpreter  on  next,
     then  evaluating  test,  and  so  on.  If a break command is
     invoked within body or  next,  then  the  for  command  will
     return immediately.  The operation of break and continue are
     similar to the corresponding statements in C.   For  returns
     an empty string.


KEYWORDS
     for, iteration, looping


_________________________________________________________________

NAME
     foreach - Iterate over all elements in a list

SYNOPSIS
     foreach varname list body
_________________________________________________________________


DESCRIPTION
     In this command varname is the name of a variable, list is a
     list  of  values  to  assign  to  varname, and body is a Tcl
     script.  For each element of list (in  order  from  left  to
     right), foreach assigns the contents of the field to varname
     as if the lindex command had been used to extract the field,
     then  calls  the Tcl interpreter to execute body.  The break
     and continue statements may be invoked inside body, with the
     same effect as in the for command.  Foreach returns an empty
     string.


KEYWORDS
     foreach, iteration, list, looping


_________________________________________________________________

NAME
     format - Format a string in the style of sprintf

SYNOPSIS
     format formatString ?arg arg ...?
_________________________________________________________________


INTRODUCTION
     This command generates a formatted string in the same way as
     the  ANSI C sprintf procedure (it uses sprintf in its imple-
     mentation).   FormatString  indicates  how  to  format   the
     result, using % conversion specifiers as in sprintf, and the
     additional arguments, if any, provide values to  be  substi-
     tuted  into the result.  The return value from format is the
     formatted string.


DETAILS ON FORMATTING
     The command operates by scanning formatString from  left  to
     right.  Each character from the format string is appended to
     the result string unless it is a percent sign.  If the char-
     acter  is  a  %  then it is not copied to the result string.
     Instead,  the  characters  following  the  %  character  are
     treated as a conversion specifier.  The conversion specifier
     controls the conversion of the next successive arg to a par-
     ticular  format  and  the  result  is appended to the result
     string in place of the conversion specifier.  If  there  are
     multiple  conversion  specifiers  in the format string, then
     each one controls the conversion of one additional arg.  The
     format  command  must be given enough args to meet the needs
     of all of the conversion specifiers in formatString.

     Each conversion specifier may contain up  to  six  different
     parts: an XPG3 position specifier, a set of flags, a minimum  |
     field width, a precision, a length modifier, and  a  conver-
     sion  character.   Any of these fields may be omitted except
     for the conversion character.  The fields that  are  present
     must  appear in the order given above.  The paragraphs below
     discuss each of these fields in turn.

     If the % is followed by a decimal number  and  a  $,  as  in  |
     ``%2$d'',  then  the  value to convert is not taken from the  |
     next sequential argument.  Instead, it  is  taken  from  the  |
     argument indicated by the number, where 1 corresponds to the  |
     first arg.  If the conversion  specifier  requires  multiple  |
     arguments because of * characters in the specifier then suc-  |
     cessive arguments are used, starting with the argument given  |
     by  the number.  This follows the XPG3 conventions for posi-  |
     tional specifiers.  If there are any  positional  specifiers  |
     in  formatString  then  all  of the specifiers must be posi-  |
     tional.

     The second portion of a conversion specifier may contain any
     of the following flag characters, in any order:

     -         Specifies that the converted  argument  should  be
               left-justified  in its field (numbers are normally
               right-justified with leading spaces if needed).

     +         Specifies that a number should always  be  printed
               with a sign, even if positive.

     space     Specifies that a space  should  be  added  to  the
               beginning  of  the  number  if the first character
               isn't a sign.

     0         Specifies that the number should be padded on  the
               left with zeroes instead of spaces.

     #         Requests an alternate output form.  For  o  and  O
               conversions  it guarantees that the first digit is
               always 0.  For  x  or  X  conversions,  0x  or  0X
               (respectively)  will  be added to the beginning of
               the result unless it is zero.  For  all  floating-
               point  conversions  (e, E, f, g, and G) it guaran-
               tees that the result always has a  decimal  point.
               For g and G conversions it specifies that trailing
               zeroes should not be removed.

     The third portion of a conversion specifier is a number giv-
     ing  a minimum field width for this conversion.  It is typi-
     cally used to make columns line up in tabular printouts.  If
     the  converted  argument  contains fewer characters than the
     minimum field width then it will be padded so that it is  as
     wide as the minimum field width.  Padding normally occurs by
     adding extra spaces on the left of the  converted  argument,
     but  the  0  and - flags may be used to specify padding with
     zeroes on the left or with  spaces  on  the  right,  respec-
     tively.  If the minimum field width is specified as * rather
     than a number, then the next argument to the format  command
     determines  the  minimum  field  width; it must be a numeric
     string.

     The fourth portion of a conversion specifier is a precision,
     which consists of a period followed by a number.  The number
     is used in different ways for different conversions.  For e,
     E,  and  f  conversions it specifies the number of digits to
     appear to the right of the  decimal  point.   For  g  and  G
     conversions  it  specifies  the  total  number  of digits to
     appear, including those on both sides of the  decimal  point
     (however, trailing zeroes after the decimal point will still
     be omitted unless the  #  flag  has  been  specified).   For
     integer conversions, it specifies a mimimum number of digits
     to print (leading zeroes will be added if necessary).  For s
     conversions it specifies the maximum number of characters to
     be printed; if the string  is  longer  than  this  then  the
     trailing  characters  will  be dropped.  If the precision is
     specified with * rather than a number then the next argument
     to the format command determines the precision; it must be a
     numeric string.

     The fourth part of a conversion specifier is a length modif-
     ier, which must be h or l.  If it is h it specifies that the
     numeric value should be truncated to a 16-bit  value  before
     converting.   This  option is rarely useful.  The l modifier
     is ignored.

     The last thing in a conversion specifier  is  an  alphabetic
     character  that  determines  what kind of conversion to per-
     form.  The following  conversion  characters  are  currently
     supported:

     d         Convert integer to signed decimal string.

     u         Convert integer to unsigned decimal string.

     i         Convert integer to  signed  decimal  string;   the
               integer may either be in decimal, in octal (with a
               leading 0) or in hexadecimal (with a leading 0x).

     o         Convert integer to unsigned octal string.

     x or X    Convert integer to  unsigned  hexadecimal  string,
               using   digits   ``0123456789abcdef''  for  x  and
               ``0123456789ABCDEF'' for X).

     c         Convert  integer  to  the   8-bit   character   it
               represents.

     s         No conversion; just insert string.

     f         Convert floating-point number  to  signed  decimal
               string of the form xx.yyy, where the number of y's
               is determined by the precision (default:  6).   If
               the  precision  is 0 then no decimal point is out-
               put.

     e or e    Convert floating-point number to scientific  nota-
               tion  in  the  form x.yyye+__zz, where the number of
               y's is determined by the precision  (default:  6).
               If  the  precision  is  0 then no decimal point is
               output.  If the E form is used then E  is  printed
               instead of e.

     g or G    If the exponent is less than -4 or greater than or
               equal  to  the  precision,  then convert floating-
               point number as for %e or %E.   Otherwise  convert
               as for %f.  Trailing zeroes and a trailing decimal
               point are omitted.

     %         No conversion: just insert %.

     For the numerical conversions the argument  being  converted
     must be an integer or floating-point string; format converts
     the argument to binary and then converts it back to a string
     according to the conversion specifier.


DIFFERENCES FROM ANSI SPRINTF
     The behavior of the format command is the same as the ANSI C  |
     sprintf procedure except for the following differences:       |

     [1]                                                                ||
          %p and %n specifiers are not currently supported.

     [2]  For %c conversions  the  argument  must  be  a  decimal
          string, which will then be converted to the correspond-
          ing character value.

     [3]  The l modifier is ignored;  integer values  are  always  |
          converted as if there were no modifier present and real  |
          values are always converted as if the l  modifier  were  |
          present  (i.e.  type  double  is  used for the internal  |
          representation).  If the h modifier is  specified  then  |
          integer  values  are  truncated to short before conver-  |
          sion.


KEYWORDS
     conversion specifier, format, sprintf, string, substitution


_________________________________________________________________

NAME
     gets - Read a line from a file

SYNOPSIS
     gets fileId ?varName?
_________________________________________________________________


DESCRIPTION
     This command reads the next line  from  the  file  given  by
     fileId  and  discards the terminating newline character.  If
     varName is specified then the line is placed in the variable
     by  that  name and the return value is a count of the number
     of characters read (not including the newline).  If the  end
     of the file is reached before reading any characters then -1
     is returned and varName is set to an empty string.  If  var-
     Name is not specified then the return value will be the line
     (minus the newline character) or an empty string if the  end
     of  the  file  is reached before reading any characters.  An
     empty string will also be returned if  a  line  contains  no
     characters except the newline, so eof may have to be used to
     determine what really happened.  If the  last  character  in
     the  file is not a newline character then gets behaves as if
     there were an additional newline character at the end of the
     file.   FileId must be stdin or the return value from a pre-
     vious call to open; it must refer to a file that was  opened
     for reading.  Any existing end-of-file or error condition on  |
     the file is cleared at the beginning of the gets command.


KEYWORDS
     file, line, read


_________________________________________________________________

NAME
     glob - Return names of files that match patterns

SYNOPSIS
     glob ?switches? pattern ?pattern ...?
_________________________________________________________________


DESCRIPTION
     This command performs file name ``globbing''  in  a  fashion
     similar  to  the  csh shell.  It returns a list of the files
     whose names match any of the pattern arguments.

     If the initial arguments to glob start with - then they  are  |
     treated  as  switches.  The following switches are currently  |
     supported:                                                    |

     -nocomplain
                    Allows an empty list to be  returned  without  |
                    error;   without  this  switch  an  error  is  |
                    returned if the result list would be empty.    |

     --                                                                 ||
                    Marks the end of switches.  The argument fol-  |
                    lowing this one will be treated as a  pattern  |
                    even if it starts with a -.

     The pattern arguments may contain any of the following  spe-
     cial characters:

     ?         Matches any single character.

     *         Matches any sequence of zero or more characters.

     [chars]   Matches any single character in chars.   If  chars
               contains a sequence of the form a-b then any char-
               acter between a and b (inclusive) will match.

     \x        Matches the character x.

     {a,b,...} Matches any of the strings a, b, etc.

     As with csh, a  ``.'' at the beginning of a file's  name  or
     just  after  a ``/'' must be matched explicitly or with a {}
     construct.   In  addition,  all  ``/''  characters  must  be
     matched explicitly.

     If the first character in a pattern is ``~'' then it  refers
     to  the  home  directory for the user whose name follows the
     ``~''.  If the ``~'' is followed immediately by  ``/''  then
     the value of the HOME environment variable is used.

     The glob command differs from  csh  globbing  in  two  ways.
     First,  it does not sort its result list (use the lsort com-
     mand if you  want  the  list  sorted).   Second,  glob  only  |
     returns  the  names of files that actually exist;  in csh no  |
     check for existence is made unless a pattern contains  a  ?,  |
     *, or [] construct.


KEYWORDS
     exist, file, glob, pattern


_________________________________________________________________

NAME
     global - Access global variables

SYNOPSIS
     global varname ?varname ...?
_________________________________________________________________


DESCRIPTION
     This command is ignored unless  a  Tcl  procedure  is  being
     interpreted.   If so then it declares the given varname's to
     be global variables rather than local ones.  For  the  dura-
     tion  of  the current procedure (and only while executing in
     the current procedure), any reference to any of the varnames
     will refer to the global variable by the same name.


KEYWORDS
     global, procedure, variable


_________________________________________________________________

NAME
     history - Manipulate the history list

SYNOPSIS
     history ?option? ?arg arg ...?
_________________________________________________________________


DESCRIPTION
     The history  command  performs  one  of  several  operations
     related  to recently-executed commands recorded in a history
     list.  Each of these recorded commands is referred to as  an
     ``event''.  When specifying an event to the history command,
     the following forms may be used:

     [1]  A number:  if positive, it refers  to  the  event  with
          that  number  (all  events are numbered starting at 1).
          If the number is negative, it selects an event relative
          to  the current event (-1 refers to the previous event,
          -2 to the one before that, and so on).

     [2]  A string:  selects the most recent event  that  matches
          the string.  An event is considered to match the string
          either if the string is the same as the  first  charac-
          ters  of  the event, or if the string matches the event
          in the sense of the string match command.

     The history command can take any of the following forms:

     history
          Same as history info, described below.

     history add command ?exec?
          Adds the command argument to the history list as a  new
          event.   If exec is specified (or abbreviated) then the
          command is also executed and its  result  is  returned.
          If  exec  isn't  specified  then  an  empty  string  is
          returned as result.

     history change newValue ?event?
          Replaces the value recorded for an event with newValue.
          Event  specifies  the event to replace, and defaults to
          the current event (not  event  -1).   This  command  is
          intended  for  use in commands that implement new forms
          of history substitution and wish to replace the current
          event (which invokes the substitution) with the command
          created through substitution.  The return value  is  an
          empty string.

     history event ?event?
          Returns the value of the event given by  event.   Event
          defaults  to  -1.  This command causes history revision
          to occur: see below for details.

     history info ?count?
          Returns a formatted  string  (intended  for  humans  to
          read)  giving the event number and contents for each of
          the events in  the  history  list  except  the  current
          event.  If count is specified then only the most recent
          count events are returned.

     history keep count
          This command may be used to change the size of the his-
          tory  list  to  count events.  Initially, 20 events are
          retained in the history list.  This command returns  an
          empty string.

     history nextid
          Returns the number of the next event to be recorded  in
          the  history list.  It is useful for things like print-
          ing the event number in command-line prompts.

     history redo ?event?
          Re-executes the command indicated by event  and  return
          its  result.   Event  defaults  to  -1.   This  command
          results in history revision:  see below for details.

     history substitute old new ?event?
          Retrieves the command given by event (-1  by  default),
          replace  any  occurrences  of old by new in the command
          (only simple character equality is supported;  no  wild
          cards),  execute  the resulting command, and return the
          result of that execution.  This command results in his-
          tory revision:  see below for details.

     history words selector ?event?
          Retrieves from  the  command  given  by  event  (-1  by
          default)  the words given by selector, and return those
          words in a string separated by  spaces.   The  selector
          argument  has  three  forms.   If it is a single number
          then it selects the word given by that  number  (0  for
          the command name, 1 for its first argument, and so on).
          If it consists of two numbers separated by a dash, then
          it selects all the arguments between those two.  Other-
          wise selector is treated as a pattern; all words match-
          ing  that  pattern  (in  the sense of string match) are
          returned.  In the numeric forms $ may be used to select
          the  last  word of a command.  For example, suppose the
          most recent command in the history list is

               format  {%s is %d years old} Alice [expr $ageInMonths/12]
          Below are some history commands and  the  results  they
          would produce:


               history words $ [expr $ageInMonths/12]
               history words 1-2{%s is %d years  old} Alice
               history words *a*o*{%s is %d years old} [expr $ageInMonths/12]
          History words results in history revision:   see  below
          for details.

HISTORY REVISION
     The history  options  event,  redo,  substitute,  and  words
     result  in  ``history revision''.  When one of these options
     is invoked then the current event is modified  to  eliminate
     the  history  command  and replace it with the result of the
     history command.  For example, suppose that the most  recent
     command in the history list is

          set a [expr $b+2]
     and suppose that the next command invoked is one of the ones
     on  the  left side of the table below.  The command actually
     recorded in the history event will be the corresponding  one
     on the right side of the table.


          history redo    set a [expr $b+2]
          history s a b   set b [expr $b+2]
          set c [history w 2]set c [expr $b+2]
     History revision is needed because event specifiers like  -1
     are  only valid at a particular time:  once more events have
     been added to the history list a different  event  specifier
     would  be needed.  History revision occurs even when history
     is invoked indirectly from the current event  (e.g.  a  user
     types  a  command  that invokes a Tcl procedure that invokes
     history):  the top-level command whose execution  eventually
     resulted  in  a history command is replaced.  If you wish to
     invoke commands like history words without history revision,
     you  can use history event to save the current history event
     and then use history change to restore it later.


KEYWORDS
     event, history, record, revision


_________________________________________________________________

NAME
     if - Execute scripts conditionally

SYNOPSIS
     if expr1 ?then? body1 elseif expr2 ?then? body2  elseif  ...
     ?else? ?bodyN?
_________________________________________________________________


DESCRIPTION
     The if command evaluates expr1 as an expression (in the same
     way  that  expr  evaluates  its argument).  The value of the
     expression must be a boolean (a numeric value,  where  0  is  |
     false  and  anything is true, or a string value such as true  |
     or yes for true and false or no for false); if  it  is  true
     then body1 is executed by passing it to the Tcl interpreter.
     Otherwise expr2 is evaluated as an expression and if  it  is
     true  then  body2  is  executed,  and so on.  If none of the
     expressions evaluates to true then bodyN is  executed.   The
     then and else arguments are optional ``noise words'' to make
     the command easier to read.  There  may  be  any  number  of
     elseif  clauses,  including zero.  BodyN may also be omitted
     as long as else is omitted too.  The return value  from  the
     command  is the result of the body script that was executed,
     or an empty string if none of the expressions  was  non-zero
     and there was no bodyN.


KEYWORDS
     boolean, conditional, else, false, if, true


_________________________________________________________________

NAME
     incr - Increment the value of a variable

SYNOPSIS
     incr varName ?increment?
_________________________________________________________________


DESCRIPTION
     Increments the value stored in the variable  whose  name  is
     varName.   The value of the variable must be an integer.  If
     increment is supplied then  its  value  (which  must  be  an
     integer)  is added to the value of variable varName;  other-
     wise 1 is added to varName.  The new value is  stored  as  a
     decimal  string  in  variable  varName  and also returned as
     result.


KEYWORDS
     add, increment, variable, value


_________________________________________________________________

NAME
     info - Return information about the state of the Tcl  inter-
     preter

SYNOPSIS
     info option ?arg arg ...?
_________________________________________________________________


DESCRIPTION
     This command provides information about various internals of
     the  Tcl  interpreter.   The  legal  option's  (which may be
     abbreviated) are:

     info args procname
          Returns a list containing the names of the arguments to
          procedure  procname,  in  order.   Procname must be the
          name of a Tcl command procedure.

     info body procname
          Returns the body of procedure procname.  Procname  must
          be the name of a Tcl command procedure.

     info cmdcount
          Returns a count of the total number  of  commands  that
          have been invoked in this interpreter.

     info commands ?pattern?
          If pattern isn't specified, returns a list of names  of
          all  the Tcl commands, including both the built-in com-
          mands written in C and the command  procedures  defined
          using  the proc command.  If pattern is specified, only
          those names matching pattern are returned.  Matching is
          determined using the same rules as for string match.

     info complete command
          Returns 1 if command is a complete Tcl command  in  the
          sense of having no unclosed quotes, braces, brackets or
          array element names, If the command doesn't  appear  to
          be  complete then 0 is returned.  This command is typi-
          cally used in line-oriented input environments to allow
          users to type in commands that span multiple lines;  if
          the  command  isn't  complete,  the  script  can  delay
          evaluating it until additional lines have been typed to
          complete the command.

     info default procname arg varname
          Procname must be the name of a  Tcl  command  procedure
          and  arg  must  be the name of an argument to that pro-
          cedure.  If arg doesn't have a default value  then  the
          command  returns  0.  Otherwise it returns 1 and places
          the default value of arg into variable varname.

     info exists varName
          Returns 1 if the variable named varName exists  in  the
          current context (either as a global or local variable),
          returns 0 otherwise.

     info globals ?pattern?
          If pattern isn't specified, returns a list of  all  the
          names  of  currently-defined global variables.  If pat-
          tern is specified, only those  names  matching  pattern
          are  returned.   Matching  is determined using the same
          rules as for string match.

     info level ?number?
          If number is not  specified,  this  command  returns  a
          number  giving  the  stack  level  of the invoking pro-
          cedure, or 0 if the command is  invoked  at  top-level.
          If  number is specified, then the result is a list con-
          sisting of the name and  arguments  for  the  procedure
          call  at level number on the stack.  If number is posi-
          tive then it selects a particular stack level (1 refers
          to the top-most active procedure, 2 to the procedure it
          called, and so on); otherwise it gives a level relative
          to  the  current  level  (0  refers to the current pro-
          cedure, -1 to its caller, and so on).  See the  uplevel
          command for more information on what stack levels mean.

     info library
          Returns the name of  the  library  directory  in  which
          standard Tcl scripts are stored.  The default value for
          the library is compiled into Tcl, but it may  be  over-
          ridden by setting the TCL_LIBRARY environment variable.
          If there is no TCL_LIBRARY variable and no  compiled-in
          value  then  and  error  is generated.  See the library
          manual entry for details of the facilities provided  by
          the Tcl script library.  Normally each application will
          have its own  application-specific  script  library  in
          addition  to  the  Tcl  script library;  I suggest that
          each application set a global variable with a name like
          $app_library  (where  app is the application's name) to
          hold the location of that application's library  direc-
          tory.

     info locals ?pattern?
          If pattern isn't specified, returns a list of  all  the
          names  of  currently-defined local variables, including
          arguments to the current procedure, if any.   Variables
          defined  with the global and upvar commands will not be
          returned.  If pattern is specified,  only  those  names
          matching  pattern are returned.  Matching is determined
          using the same rules as for string match.

     info patchlevel
          Returns a decimal  integer  giving  the  current  patch  |
          level for Tcl.  The patch level is incremented for each  |
          new release or patch, and  it  uniquely  identifies  an  |
          official version of Tcl.

     info procs ?pattern?
          If pattern isn't specified, returns a list of  all  the
          names  of Tcl command procedures.  If pattern is speci-
          fied, only those names matching pattern  are  returned.
          Matching  is  determined  using  the  same rules as for
          string match.

     info script
          If a Tcl script file is currently being evaluated (i.e.
          there  is  a call to Tcl_EvalFile active or there is an
          active invocation of the  source  command),  then  this
          command  returns  the  name of the innermost file being
          processed.  Otherwise  the  command  returns  an  empty
          string.

     info tclversion
          Returns the version number for this version of  Tcl  in
          the  form  x.y,  where  changes  to  x  represent major
          changes with probable incompatibilities and changes  to
          y  represent  small  enhancements  and  bug  fixes that
          retain backward compatibility.

     info vars ?pattern?
          If pattern isn't specified, returns a list of  all  the
          names  of  currently-visible  variables, including both
          locals and currently-visible globals.   If  pattern  is
          specified,   only  those  names  matching  pattern  are
          returned.  Matching is determined using the same  rules
          as for string match.


KEYWORDS
     command, information, interpreter, level,  procedure,  vari-
     able


_________________________________________________________________

NAME
     join - Create a string by joining together list elements

SYNOPSIS
     join list ?joinString?
_________________________________________________________________


DESCRIPTION
     The list argument must be a valid Tcl  list.   This  command
     returns  the string formed by joining all of the elements of
     list together with joinString separating each adjacent  pair
     of  elements.   The  joinString argument defaults to a space
     character.


KEYWORDS
     element, join, list, separator


_________________________________________________________________

NAME
     lappend - Append list elements onto a variable

SYNOPSIS
     lappend varName value ?value value ...?
_________________________________________________________________


DESCRIPTION
     This command treats the variable given by varName as a  list
     and  appends  each  of the value arguments to that list as a
     separate element, with spaces between elements.  If  varName
     doesn't  exist,  it is created as a list with elements given
     by the value arguments.  Lappend is similar to append except
     that  the  values  are appended as list elements rather than
     raw text.  This command provides a relatively efficient  way
     to  build  up large lists.  For example, ``lappend a $b'' is
     much more efficient than ``set a  [concat  $a  [list  $b]]''
     when $a is long.


KEYWORDS
     append, element, list, variable


_________________________________________________________________

NAME
     library - standard library of Tcl procedures

SYNOPSIS
     auto_execok cmd
     auto_load cmd
     auto_mkindex dir pattern pattern ...
     auto_reset
     parray arrayName
     unknown cmd ?arg arg ...?
_________________________________________________________________


INTRODUCTION
     Tcl includes a library of Tcl procedures for commonly-needed
     functions.   The  procedures  defined in the Tcl library are
     generic ones suitable for use  by  many  different  applica-
     tions.   The  location of the Tcl library is returned by the
     info library command.  In addition to the Tcl library,  each
     application  will  normally  have its own library of support
     procedures as well;  the location of this  library  is  nor-
     mally  given  by  the value of the $app_library global vari-
     able, where app is the name of the application.   For  exam-
     ple,  the location of the Tk library is kept in the variable
     $tk_library.

#      To access the procedures in the Tcl library, an  application
#      should  source the file init.tcl in the library, for example
#      with the Tcl command
# 
#           source [info library]/init.tcl
#      This will define the unknown procedure and arrange  for  the
#      other  procedures to be loaded on-demand using the auto-load
#      mechanism defined below.


COMMAND PROCEDURES
     The following procedures are provided in the Tcl library:

     auto_execok cmd
          Determines whether there is an executable file  by  the
          name cmd.  This command examines the directories in the
          current search path  (given  by  the  PATH  enviornment
          variable)  to  see if there is an executable file named
          cmd in any of those directories.  If so, it returns  1;
          if  not  it returns 0.  Auto_exec remembers information
          about previous searches in an array  named  auto_execs;
          this  avoids  the  path  search in future calls for the
          same cmd.  The command auto_reset may be used to  force
          auto_execok to forget its cached information.

     auto_load cmd
          This command attempts to load the definition for a  Tcl
          command  named  cmd.   To do this, it searches an auto-
          load path, which is a list of one or more  directories.
          The  auto-load  path  is  given  by the global variable
          $auto_path if it exists.  If  there  is  no  $auto_path
          variable,  then  the TCLLIBPATH environment variable is
          used, if it exists.  Otherwise the auto-load path  con-
          sists  of  just the Tcl library directory.  Within each
          directory in the auto-load path there must  be  a  file
          tclIndex that describes one or more commands defined in  |
          that directory and a script to evaluate to load each of  |
          the  commands.   The  tclIndex file should be generated  |
          with the auto_mkindex command.  If cmd is found  in  an  |
          index file, then the appropriate script is evaluated to  |
          create the command.  The auto_load command returns 1 if
          cmd was successfully created.  The command returns 0 if
          there was no index entry  for  cmd  or  if  the  script
          didn't actually define cmd (e.g. because index informa-
          tion is out of date).  If an error  occurs  while  pro-
          cessing  the  script,  then  that  error  is  returned.
          Auto_load only reads the  index  information  once  and
          saves  it  in  the  array  auto_index;  future calls to
          auto_load check for cmd in the array  rather  than  re-
          reading  the index files.  The cached index information
          may be deleted with the command auto_reset.  This  will
          force  the  next  auto_load command to reload the index
          database from disk.

     auto_mkindex dir pattern pattern ...
          Generates an index suitable for use by auto_load.   The  |
          command  searches  dir  for all files whose names match  |
          any of the pattern arguments (matching is done with the
          glob  command),  generates an index of all the Tcl com-
          mand procedures defined in all the matching files,  and
          stores  the  index information in a file named tclIndex
          in dir.  For example, the command

               auto_mkindex foo *.tcl

          will read all the .tcl files in  subdirectory  foo  and
          generate a new index file foo/tclIndex.

          Auto_mkindex parses the Tcl  scripts  in  a  relatively
          unsophisticated  way:   if  any  line contains the word
          proc as its first characters then it is assumed to be a
          procedure  definition  and the next word of the line is
          taken as the procedure's name.   Procedure  definitions
          that  don't  appear  in this way (e.g. they have spaces
          before the proc) will not be indexed.

     auto_reset
          Destroys all the information cached by auto_execok  and
          auto_load.   This information will be re-read from disk
          the next time it is needed.   Auto_reset  also  deletes
          any  procedures  listed in the auto-load index, so that
          fresh copies of them will be loaded the next time  that
          they're used.

     parray arrayName
          Prints on standard output the names and values  of  all
          the elements in the array arrayName.  ArrayName must be
          an array accessible to the caller of parray.  It may be
          either local or global.

     unknown cmd ?arg arg ...?
          This procedure is  invoked  automatically  by  the  Tcl
          interpreter  whenever  the  name  of  a command doesn't
          exist.  The unknown procedure receives as its arguments
          the name and arguments of the missing command.  Unknown  |
          first calls auto_load to load  the  command.   If  this
          succeeds,  then  it  executes the original command with
          its original arguments.  If the  auto-load  fails  then
          unknown calls auto_execok to see if there is an execut-
          able file by the name cmd.  If so, it invokes  the  Tcl
          exec  command  with  cmd and all the args as arguments.
          If cmd can't be auto-executed, unknown checks to see if
          the command was invoked at top-level and outside of any
          script.  If so, then unknown takes takes two additional
          steps.   First, it sees if cmd has one of the following
          three forms: !!, !event, or ^old^new?^?.  If  so,  then
          unknown  carries  out  history substitution in the same
          way that csh would for these constructs.   Second,  and
          last, unknown checks to see if cmd is a unique abbrevi-
          ation for an existing Tcl command.  If so,  it  expands
          the command name and executes the command with the ori-
          ginal arguments.  If none of the above efforts has been
          able to execute the command, unknown generates an error
          return.  If the global variable auto_noload is defined,
          then  the  auto-load  step  is  skipped.  If the global
          variable auto_noexec is defined then the auto-exec step
          is  skipped.   Under  normal  circumstances  the return
          value from unknown is the return value from the command
          that was eventually executed.


VARIABLES
     The following global variables are defined or  used  by  the
     procedures in the Tcl library:

     auto_execs
          Used by auto_execok to record information about whether
          particular commands exist as executable files.

     auto_index
          Used by auto_load to save the  index  information  read
          from disk.

     auto_noexec
          If set to any value, then unknown will not  attempt  to
          auto-exec any commands.

     auto_noload
          If set to any value, then unknown will not  attempt  to
          auto-load any commands.

     auto_path
          If set, then it must contain a valid  Tcl  list  giving
          directories to search during auto-load operations.

     env(TCL_LIBRARY)
          If set, then it specifies the location of the directory
          containing  library scripts (the value of this variable
          will be returned by the command info library).  If this
          variable isn't set then a default value is used.

     env(TCLLIBPATH)
          If set, then it must contain a valid  Tcl  list  giving
          directories  to  search  during  auto-load  operations.
          This variable is only used if auto_path is not defined.

     unknown_active
          This variable is set by unknown to indicate that it  is
          active.   It  is  used  to  detect errors where unknown
          recurses on itself infinitely.  The variable  is  unset
          before unknown returns.


KEYWORDS
     auto-exec, auto-load, library, unknown


_________________________________________________________________

NAME
     lindex - Retrieve an element from a list

SYNOPSIS
     lindex list index
_________________________________________________________________


DESCRIPTION
     This command treats list as  a  Tcl  list  and  returns  the
     index'th  element  from it (0 refers to the first element of
     the list).  In extracting the element, lindex  observes  the
     same  rules  concerning braces and quotes and backslashes as
     the Tcl command interpreter; however, variable  substitution
     and command substitution do not occur.  If index is negative
     or greater than or equal to the number of elements in value,
     then an empty string is returned.


KEYWORDS
     element, index, list


_________________________________________________________________

NAME
     linsert - Insert elements into a list

SYNOPSIS
     linsert list index element ?element element ...?
_________________________________________________________________


DESCRIPTION
     This command produces a new list from list by inserting  all
     of  the element arguments just before the indexth element of
     list.  Each element argument will become a separate  element
     of  the  new  list.  If index is less than or equal to zero,
     then the new elements are inserted at the beginning  of  the
     list.   If  index  is greater than or equal to the number of
     elements in the list, then the new elements are appended  to
     the list.


KEYWORDS
     element, insert, list


_________________________________________________________________

NAME
     list - Create a list

SYNOPSIS
     list ?arg arg ...?                                            |
_________________________________________________________________


DESCRIPTION
     This command returns a list comprised of all the args, or an  |
     empty   string   if  no  args  are  specified.   Braces  and
     backslashes get added as necessary, so that the  index  com-
     mand  may  be  used on the result to re-extract the original
     arguments, and also so that eval may be used to execute  the
     resulting  list, with arg1 comprising the command's name and
     the other args  comprising  its  arguments.   List  produces
     slightly  different results than concat:  concat removes one
     level of grouping before forming the list, while list  works
     directly from the original arguments.  For example, the com-
     mand

          list a b {c d e} {f {g h}}
     will return

          a b {c d e} {f {g h}}
     while concat with the same arguments will return

          a b c d e f {g h}


KEYWORDS
     element, list


_________________________________________________________________

NAME
     llength - Count the number of elements in a list

SYNOPSIS
     llength list
_________________________________________________________________


DESCRIPTION
     Treats list as a list and returns a  decimal  string  giving
     the number of elements in it.


KEYWORDS
     element, list, length


_________________________________________________________________

NAME
     lrange - Return one or more adjacent elements from a list

SYNOPSIS
     lrange list first last
_________________________________________________________________


DESCRIPTION
     List must be a valid Tcl list.  This command will  return  a
     new   list   consisting  of  elements  first  through  last,
     inclusive.  Last may be end (or any abbreviation of  it)  to
     refer  to  the  last  element of the list.  If first is less
     than zero, it is treated as if it were  zero.   If  last  is
     greater than or equal to the number of elements in the list,
     then it is treated as if it were end.  If first  is  greater
     than  last then an empty string is returned.  Note: ``lrange
     list first first'' does not always produce the  same  result
     as  ``lindex list first'' (although it often does for simple
     fields that aren't enclosed in braces);  it  does,  however,
     produce  exactly  the  same  results  as ``list [lindex list
     first]''


KEYWORDS
     element, list, range, sublist


_________________________________________________________________

NAME
     lreplace - Replace elements in a list with new elements

SYNOPSIS
     lreplace list first last ?element element ...?
_________________________________________________________________


DESCRIPTION
     Lreplace returns a new list formed by replacing one or  more
     elements  of  list  with the element arguments.  First gives
     the index in list of the first element to be  replaced.   If
     first  is less than zero then it refers to the first element
     of list;  the element indicated by first must exist  in  the
     list.   Last  gives the index in list of the last element to
     be replaced;  it must be greater than  or  equal  to  first.
     Last may be end (or any abbreviation of it) to indicate that
     all elements between first and the end of the list should be
     replaced.   The  element  arguments specify zero or more new
     arguments to be added to the list in  place  of  those  that
     were  deleted.  Each element argument will become a separate
     element of the list.  If no element arguments are specified,
     then the elements between first and last are simply deleted.


KEYWORDS
     element, list, replace


_________________________________________________________________

NAME
     lsearch - See if a list contains a particular element

SYNOPSIS
     lsearch ?mode? list pattern
_________________________________________________________________


DESCRIPTION
     This command searches the elements of list to see if one  of
     them  matches pattern.  If so, the command returns the index
     of the first matching element.  If not, the command  returns
     -1.   The  mode  argument  indicates how the elements of the  |
     list are to be matched against pattern and it must have  one  |
     of the following values:                                      |

     -exact                                                             ||
          The  list  element must contain exactly the same string  |
          as pattern.                                              |

     -glob                                                              ||
          Pattern  is  a  glob-style  pattern  which  is  matched  |
          against each list element using the same rules  as  the  |
          string match command.                                    |

     -regexp                                                            ||
          Pattern  is treated as a regular expression and matched  |
          against each list element using the same rules  as  the  |
          regexp command.                                          |

     If mode is omitted then it defaults to -glob.


KEYWORDS
     list, match, pattern, regular expression, search, string


_________________________________________________________________

NAME
     lsort - Sort the elements of a list

SYNOPSIS
     lsort ?switches? list
_________________________________________________________________


DESCRIPTION
     This command sorts the elements of  list,  returning  a  new
     list in sorted order.  By default ASCII sorting is used with
     the result returned in increasing order.   However,  any  of  |
     the  following switches may be specified before list to con-  |
     trol  the  sorting   process   (unique   abbreviations   are  |
     accepted):                                                    |

     -ascii                                                             ||
                         Use  string comparison with ASCII colla-  |
                         tion order.  This is the default.         |

     -ignore                                                             ||
                         ASCII comparison, ignore case.

     -integer                                                           ||
                         Convert  list  elements  to integers and  |
                         use integer comparison.                   |

     -real                                                              ||
                         Convert  list elements to floating-point  |
                         values and use floating comparison.       |

     -command command                                                   ||
                         Use command as a comparison command.  To  |
                         compare two  elements,  evaluate  a  Tcl  |
                         script  consisting  of  command with the  |
                         two  elements  appended  as   additional  |
                         arguments.   The script should return an  |
                         integer less than, equal to, or  greater  |
                         than  zero if the first element is to be  |
                         considered  less  than,  equal  to,   or  |
                         greater than the second, respectively.    |

     -increas-  |
                         ing                                                        ||
                         Sort  the  list  in   increasing   order  |
                         (``smallest'' items first).  This is the  |
                         default.                                  |

     -decreas-  |
                         ing                                                        ||
                         Sort  the  list  in   decreasing   order  |
                         (``largest'' items first).


KEYWORDS
     element, list, order, sort


_________________________________________________________________

NAME
     open - Open a file

SYNOPSIS
     open fileName ?access? ?permissions?                          |
_________________________________________________________________


DESCRIPTION
     This command opens a file and returns an identifier that may
     be  used  in future invocations of commands like read, puts,
     and close.  FileName gives the name of the file to open;  if
     it  starts with a tilde then tilde substitution is performed
     as described for Tcl_TildeSubst.  If the first character  of
     fileName  is ``|'' then the remaining characters of fileName
     are treated as a command pipeline to  invoke,  in  the  same
     style as for exec.  In this case, the identifier returned by
     open may be used to write to the  command's  input  pipe  or
     read from its output pipe.

     The access argument indicates the way in which the file  (or
     command pipeline) is to be accessed.  It may take two forms,  |
     either a string in the form that  would  be  passed  to  the  |
     fopen library procedure or a list of POSIX access flags.  It  |
     defaults to ``r''.  In the first form access may have any of  |
     the following values:

     r              Open the file for reading only; the file must
                    already exist.

     r+             Open the file for both reading  and  writing;
                    the file must already exist.

     w              Open the file for writing only.  Truncate  it
                    if  it exists.  If it doesn't exist, create a
                    new file.

     w+             Open the file for reading and writing.  Trun-
                    cate  it  if it exists.  If it doesn't exist,
                    create a new file.

     a              Open the file for  writing  only.   The  file
                    must  already  exist,  and  the file is posi-
                    tioned so that new data is  appended  to  the
                    file.

     a+             Open the file for reading  and  writing.   If
                    the  file  doesn't  exist, create a new empty
                    file.  Set the initial  access  position   to
                    the end of the file.

     In the second form, access consists of a list of any of  the  |
     following  flags, all of which have the standard POSIX mean-  |
     ings.  One of the flags must be  either  RDONLY,  WRONLY  or  |
     RDWR.                                                         |

     RDONLY                                                             ||
                    Open the file for reading only.                |

     WRONLY                                                             ||
                    Open the file for writing only.                |

     RDWR                                                               ||
                    Open the file for both reading and writing.    |

     APPEND                                                             ||
                    Set  the  file pointer to the end of the file  |
                    prior to each write.                           |

     CREAT                                                              ||
                    Create  the  file if it doesn't already exist  |
                    (without this flag it is  an  error  for  the  |
                    file not to exist).                            |

     EXCL                                                               ||
                    If  CREAT  is  specified  also,  an  error is  |
                    returned if the file already exists.           |

     NOCTTY                                                             ||
                    If  the  file is a terminal device, this flag  |
                    prevents the file from becoming the  control-  |
                    ling terminal of the process.                  |

     NON-  |
                    BLOCK                                                           ||
                    Prevents  the  process  from  blocking  while  |
                    opening  the file.  For details refer to your  |
                    system  documentation  on  the  open   system  |
                    call's O_NONBLOCK flag.                        |

     TRUNC                                                              ||
                    If  the  file  exists it is truncated to zero  |
                    length.                                        |

     If a new file is created as part of opening it,  permissions  |
     (an integer) is used to set the permissions for the new file  |
     in conjunction with the process's file mode  creation  mask.  |
     Permissions defaults to 0666.

     If a file is opened for both reading and writing  then  seek
     must  be  invoked  between a read and a write, or vice versa
     (this restriction does not apply to command pipelines opened
     with  open).  When fileName specifies a command pipeline and
     a write-only access is used, then standard output  from  the
     pipeline  is  directed to the current standard output unless
     overridden by the command.  When fileName specifies  a  com-
     mand  pipeline and a read-only access is used, then standard
     input from the pipeline is taken from the  current  standard
     input unless overridden by the command.


KEYWORDS
     access mode, append,  controlling  terminal,  create,  file,
     non-blocking, open, permissions, pipeline, process


_________________________________________________________________

NAME
     pid - Retrieve process id(s)

SYNOPSIS
     pid ?fileId?
_________________________________________________________________


DESCRIPTION
     If the fileId argument is  given  then  it  should  normally
     refer  to  a process pipeline created with the open command.
     In this case the pid command will return a list  whose  ele-
     ments  are  the  process identifiers of all the processes in
     the pipeline, in order.  The list will be  empty  if  fileId
     refers to an open file that isn't a process pipeline.  If no
     fileId argument is given then pid returns the process  iden-
     tifier  of the current process.  All process identifiers are
     returned as decimal strings.


KEYWORDS
     file, pipeline, process identifier


_________________________________________________________________

NAME
     proc - Create a Tcl procedure

SYNOPSIS
     proc name args body
_________________________________________________________________


DESCRIPTION
     The proc command creates a new  Tcl  procedure  named  name,
     replacing  any  existing command or procedure there may have
     been by that name.  Whenever the new command is invoked, the
     contents  of  body  will be executed by the Tcl interpreter.
     Args specifies the formal arguments to  the  procedure.   It
     consists  of  a list, possibly empty, each of whose elements
     specifies one argument.  Each argument specifier is  also  a
     list with either one or two fields.  If there is only a sin-
     gle field in the specifier then it is the name of the  argu-
     ment;  if  there are two fields, then the first is the argu-
     ment name and the second is its default value.

     When name is invoked a local variable will  be  created  for
     each  of  the  formal  arguments to the procedure; its value
     will be the value of corresponding argument in the  invoking
     command  or  the  argument's  default value.  Arguments with
     default values need not be specified in a procedure  invoca-
     tion.   However,  there  must be enough actual arguments for
     all the formal arguments that don't have defaults, and there
     must  not  be any extra actual arguments.  There is one spe-
     cial case to permit  procedures  with  variable  numbers  of
     arguments.   If  the last formal argument has the name args,
     then a call to the procedure may contain more  actual  argu-
     ments  than the procedure has formals.  In this case, all of
     the actual arguments starting  at  the  one  that  would  be
     assigned  to  args  are combined into a list (as if the list
     command had been used); this combined value is  assigned  to
     the local variable args.

     When body is being executed, variable names  normally  refer
     to  local  variables,  which  are created automatically when
     referenced and deleted  when  the  procedure  returns.   One
     local  variable  is  automatically  created  for each of the
     procedure's  arguments.   Global  variables  can   only   be
     accessed  by  invoking  the global command or the upvar com-
     mand.

     The proc command returns an empty string.  When a  procedure
     is invoked, the procedure's return value is the value speci-
     fied in a return command.  If the procedure doesn't  execute
     an  explicit  return,  then its return value is the value of
     the last command executed in the procedure's  body.   If  an
     error  occurs  while  executing the procedure body, then the
     procedure-as-a-whole will return that same error.


KEYWORDS
     argument, procedure


_________________________________________________________________

NAME
     puts - Write to a file

SYNOPSIS
     puts ?-nonewline? fileId string
_________________________________________________________________


DESCRIPTION
     Writes the characters given by string to the file  given  by
     fileId.   FileId must have been the return value from a pre-
     vious call to open; it must refer to a file that was opened
     for writing. Puts normally outputs a newline
     character after string, but this feature may  be  suppressed
     by  specifying  the  -nonewline  switch.  Output to files is
     buffered internally by Tcl; the flush command may be used to
     force buffered characters to be output.

	 Note that <stdout> is not supported in Alpha!

KEYWORDS
     file, newline, output, write


_________________________________________________________________

NAME
     pwd - Return the current working directory

SYNOPSIS
     pwd
_________________________________________________________________


DESCRIPTION
     Returns the path name of the current working directory.


KEYWORDS
     working directory


_________________________________________________________________

NAME
     read - Read from a file

SYNOPSIS
     read ?-nonewline? fileId
     read fileId numBytes
_________________________________________________________________


DESCRIPTION
     In the first form, all of the remaining bytes are read  from
     the file given by fileId; they are returned as the result of
     the command.  If the -nonewline switch is specified then the
     last  character of the file is discarded if it is a newline.
     In the second form, the extra argument  specifies  how  many
     bytes  to  read;  exactly  this  many bytes will be read and
     returned, unless there are fewer than numBytes bytes left in
     the  file;  in  this  case,  all  the  remaining  bytes  are
     returned.  FileId must be stdin or the return value  from  a
     previous  call  to  open;  it  must refer to a file that was
     opened for reading.  Any existing end-of-file or error  con-  |
     dition  on  the file is cleared at the beginning of the read  |
     command.


KEYWORDS
     file, read


_________________________________________________________________

NAME
     regexp - Match a regular expression against a string

SYNOPSIS
     regexp ?switches? exp string  ?matchVar?  ?subMatchVar  sub-
     MatchVar ...?
_________________________________________________________________


DESCRIPTION
     Determines whether the regular expression exp  matches  part
     or all of string and returns 1 if it does, 0 if it doesn't.

     If additional arguments are specified after string then they
     are  treated  as  the  names of variables in which to return
     information about  which  part(s)  of  string  matched  exp.
     MatchVar will be set to the range of string that matched all
     of exp.  The first subMatchVar will contain  the  characters
     in string that matched the leftmost parenthesized subexpres-
     sion within exp, the next subMatchVar will contain the char-
     acters  that matched the next parenthesized subexpression to
     the right in exp, and so on.

     If the initial arguments to regexp start with  -  then  they  |
     are   treated  as  switches.   The  following  switches  are  |
     currently supported:                                          |

     -nocase                                                            ||
               Causes  upper-case  characters  in  string  to  be  |
               treated as lower case during the matching process.  |

     -indices                                                           ||
               Changes   what  is  stored  in  the  subMatchVars.  |
               Instead of storing the  matching  characters  from  |
               string,  each  variable will contain a list of two  |
               decimal strings giving the indices  in  string  of  |
               the  first  and  last  characters  in the matching  |
               range of characters.                                |

     --                                                                 ||
               Marks the end of switches.  The argument following  |
               this one will be treated as exp even if it  starts  |
               with a -.

     If there are more subMatchVar's  than  parenthesized  subex-
     pressions  within  exp,  or if a particular subexpression in
     exp doesn't match the string (e.g. because it was in a  por-
     tion  of  the  expression  that  wasn't  matched),  then the
     corresponding subMatchVar  will  be  set  to  ``-1  -1''  if
     -indices has been specified or to an empty string otherwise.

REGULAR EXPRESSIONS
     Regular expressions are implemented  using  Henry  Spencer's
     package  (thanks,  Henry!),  and  much of the description of
     regular expressions below is copied verbatim from his manual
     entry.

     A regular expression is zero or more branches, separated  by
     ``|''.    It  matches  anything  that  matches  one  of  the
     branches.

     A branch is zero or more pieces, concatenated.  It matches a
     match  for  the  first,  followed by a match for the second,
     etc.

     A piece is an atom possibly followed  by  ``*'',  ``+'',  or
     ``?''.  An atom followed by ``*'' matches a sequence of 0 or
     more matches of the atom.  An atom followed by ``+'' matches
     a  sequence  of 1 or more matches of the atom.  An atom fol-
     lowed by ``?'' matches a match of  the  atom,  or  the  null
     string.

     An atom is a regular expression in parentheses  (matching  a
     match  for  the  regular  expression),  a range (see below),
     ``.'' (matching any single character), ``^''  (matching  the
     null  string  at  the  beginning of the input string), ``$''
     (matching the null string at the end of the input string), a
     ``\''  followed by a single character (matching that charac-
     ter), or a  single  character  with  no  other  significance
     (matching that character).

     A range is a sequence of characters enclosed in ``[]''.   It
     normally matches any single character from the sequence.  If
     the sequence begins with ``^'', it matches any single  char-
     acter  not from the rest of the sequence.  If two characters
     in the sequence are separated by ``-'',  this  is  shorthand
     for  the  full  list  of ASCII characters between them (e.g.
     ``[0-9]'' matches any decimal digit).  To include a  literal
     ``]''  in the sequence, make it the first character (follow-
     ing a possible ``^'').  To include a literal ``-'', make  it
     the first or last character.


CHOOSING AMONG ALTERNATIVE MATCHES
     In general there may be more than one way to match a regular
     expression  to  an  input string.  For example, consider the
     command

          regexp  (a*)b*  aabaaabb  x  y
     Considering only the rules given so far, x and y  could  end
     up  with  the values aabb and aa, aaab and aaa, ab and a, or
     any of several other combinations.  To resolve  this  poten-
     tial  ambiguity  regexp chooses among alternatives using the
     rule ``first then longest''.  In other  words,  it  consders
     the  possible  matches  in  order working from left to right
     across the input string and the pattern, and it attempts  to
     match longer pieces of the input string before shorter ones.
     More specifically, the following rules apply  in  decreasing
     order of priority:

     [1]  If a regular expression could match two different parts
          of  an  input  string  then  it will match the one that
          begins earliest.

     [2]  If a regular expression contains | operators  then  the
          leftmost matching sub-expression is chosen.

     [3]  In *, +, and ? constructs, longer matches are chosen in
          preference to shorter ones.

     [4]  In sequences of expression  components  the  components
          are considered from left to right.

     In the example from above, (a*)b*  matches  aab:   the  (a*)
     portion  of the pattern is matched first and it consumes the
     leading aa; then the b* portion of the pattern consumes  the
     next b.  Or, consider the following example:

          regexp  (ab|a)(b*)c  abc  x  y  z
     After this command x will be abc, y will be ab, and  z  will
     be an empty string.  Rule 4 specifies that (ab|a) gets first
     shot at the input string and Rule 2 specifies  that  the  ab
     sub-expression is checked before the a sub-expression.  Thus
     the b has already been claimed before the (b*) component  is
     checked and (b*) must match an empty string.


KEYWORDS
     match, regular expression, string


_________________________________________________________________

NAME
     regsub - Perform substitutions based on  regular  expression
     pattern matching

SYNOPSIS
     regsub ?switches? exp string subSpec varName
_________________________________________________________________


DESCRIPTION
     This command matches  the  regular  expression  exp  against
     string,  and  it copies string to the variable whose name is  |
     given by varName.  The command returns 1 if there is a match  |
     and 0 if there isn't.  If there is a match, then while copy-  |
     ing string to varName the portion of string that matched exp
     is  replaced  with  subSpec.  If subSpec contains a ``&'' or
     ``\0'', then it is replaced in  the  substitution  with  the
     portion  of  string that matched exp.  If subSpec contains a
     ``\n'', where n is a digit between  1  and  9,  then  it  is
     replaced in the substitution with the portion of string that
     matched the n-th parenthesized subexpression of exp.   Addi-
     tional backslashes may be used in subSpec to prevent special
     interpretation of ``&'' or ``\0'' or  ``\n''  or  backslash.
     The  use  of  backslashes in subSpec tends to interact badly
     with the Tcl parser's use of backslashes, so it's  generally
     safest   to   enclose  subSpec  in  braces  if  it  includes
     backslashes.

     If the initial arguments to regexp start with  -  then  they  |
     are   treated  as  switches.   The  following  switches  are  |
     currently supported:                                          |

     -all                                                               ||
               All  ranges in string that match exp are found and  |
               substitution  is  performed  for  each  of   these  |
               ranges.  Without this switch only the first match-  |
               ing range is found and substituted.   If  -all  is  |
               specified,  then  ``&''  and  ``\n'' sequences are  |
               handled for each substitution using  the  informa-  |
               tion from the corresponding match.                  |

     -nocase                                                            ||
               Upper-case  characters in string will be converted  |
               to lower-case before matching against  exp;   how-  |
               ever,  substitutions  specified by subSpec use the  |
               original unconverted form of string.                |

     --                                                                 ||
               Marks the end of switches.  The argument following  |
               this one will be treated as exp even if it  starts  |
               with a -.

     See the manual entry for regexp for details on the interpre-
     tation of regular expressions.


KEYWORDS
     match, pattern, regular expression, substitute


_________________________________________________________________

NAME
     rename - Rename or delete a command

SYNOPSIS
     rename oldName newName
_________________________________________________________________


DESCRIPTION
     Rename the command that used to be called oldName so that it
     is  now  called newName.  If newName is an empty string then
     oldName is deleted.  The rename  command  returns  an  empty
     string as result.


KEYWORDS
     command, delete, rename


_________________________________________________________________

NAME
     return - Return from a procedure

SYNOPSIS
     return ?-code  code?  ?-errorinfo  info?  ?-errorcode  code?
     ?string?
_________________________________________________________________


DESCRIPTION
     Return immediately from the current procedure (or  top-level
     command or source command), with string as the return value.
     If string is not specified then  an  empty  string  will  be
     returned as result.


EXCEPTIONAL RETURNS
     In the usual case where the -code option isn't specified the  |
     procedure  will return normally (its completion code will be  |
     TCL_OK).  However, the -code option may be used to  generate  |
     an exceptional return from the procedure.  Code may have any  |
     of the following values:                                      |

     ok                                                                 ||
               Normal return:  same as if the option is omitted.   |

     error                                                              ||
               Error  return:  same  as if the error command were  |
               used to terminate the procedure, except  for  han-  |
               dling  of  errorInfo  and errorCode variables (see  |
               below).                                             |

     return                                                             ||
               The  current  procedure will return with a comple-  |
               tion code of TCL_RETURN,  so  that  the  procedure  |
               that invoked it will return also.                   |

     break                                                              ||
               The  current  procedure will return with a comple-  |
               tion code of TCL_BREAK, which will  terminate  the  |
               innermost nested loop in the code that invoked the  |
               current procedure.                                  |

     con-  |
               tinue                                                           ||
               The current procedure will return with  a  comple-  |
               tion  code  of  TCL_CONTINUE, which will terminate  |
               the current iteration of the innermost nested loop  |
               in the code that invoked the current procedure.     |

     value                                                              ||
               Value  must be an integer;  it will be returned as  |
               the completion code for the current procedure.      |

     The -code option is rarely used.  It  is  provided  so  that  |
     procedures that implement new control structures can reflect  |
     exceptional conditions back to their callers.                 |

     Two additional options, -errorinfo and  -errorcode,  may  be  |
     used to provide additional information during error returns.  |
     These options are ignored unless code is error.               |

     The -errorinfo option specifies an initial stack  trace  for  |
     the  errorInfo  variable;   if  it is not specified then the  |
     stack trace left in errorInfo will include the call  to  the  |
     procedure  and  higher  levels  on the stack but it will not  |
     include any information  about  the  context  of  the  error  |
     within  the procedure.  Typically the info value is supplied  |
     from the value left  in  errorInfo  after  a  catch  command  |
     trapped an error within the procedure.                        |

     If the -errorcode option is specified then code  provides  a  |
     value  for  the  errorCode  variable.   If the option is not  |
     specified then errorCode will default to NONE.


KEYWORDS
     break, continue, error, procedure, return


_________________________________________________________________

NAME
     scan - Parse string using conversion specifiers in the style
     of sscanf

SYNOPSIS
     scan string format varName ?varName ...?
_________________________________________________________________


INTRODUCTION
     This command parses fields from an input string in the  same
     fashion  as  the ANSI C sscanf procedure and returns a count
     of the number of fields sucessfully  parsed.   String  gives
     the input to be parsed and format indicates how to parse it,
     using % conversion specifiers as in  sscanf.   Each  varName
     gives  the  name of a variable; when a field is scanned from
     string the result  is  converted  back  into  a  string  and
     assigned to the corresponding variable.


DETAILS ON SCANNING
     Scan operates by scanning string and formatString  together.
     If the next character in formatString is a blank or tab then
     it is ignored.  Otherwise, if it isn't a % character then it
     must  match  the  next  non-white-space character of string.
     When a % is encountered in formatString,  it  indicates  the
     start  of  a  conversion  specifier.  A conversion specifier
     contains three fields after the %: a *, which indicates that
     the  converted  value is to be discarded instead of assigned
     to a variable; a number indicating a  maximum  field  width;
     and  a  conversion  character.   All  of  these  fields  are
     optional except for the conversion character.

     When scan finds a conversion specifier in  formatString,  it
     first  skips  any white-space characters in string.  Then it
     converts the next input characters according to the  conver-
     sion  specifier  and stores the result in the variable given
     by the next argument  to  scan.   The  following  conversion
     characters are supported:

     d         The input field must be a decimal integer.  It  is
               read in and the value is stored in the variable as
               a decimal string.

     o         The input field must be an octal  integer.  It  is
               read in and the value is stored in the variable as
               a decimal string.

     x         The input field must be a hexadecimal integer.  It
               is read in and the value is stored in the variable
               as a decimal string.

     c         A single character is read in and its binary value
               is  stored  in  the  variable as a decimal string.
               Initial white space is not skipped in  this  case,
               so the input field may be a white-space character.
               This conversion is different from the  ANSI  stan-
               dard  in that the input field always consists of a
               single character and no field width may be  speci-
               fied.

     s         The input field consists of all the characters  up
               to  the next white-space character; the characters
               are copied to the variable.

     e or f or g
               The input field must be  a  floating-point  number
               consisting  of  an  optional  sign,  a  string  of
               decimal digits  possibly  con  taining  a  decimal
               point, and an optional exponent consisting of an e
               or E followed by an optional sign and a string  of
               decimal  digits.   It is read in and stored in the
               variable as a floating-point string.

     [chars]   The input field consists of any number of  charac-
               ters  in  chars.  The matching string is stored in
               the variable.  If the first character between  the
               brackets  is  a  ]  then  it is treated as part of
               chars rather than the closing bracket for the set.

     [^chars]  The input field consists of any number of  charac-
               ters  not in chars.  The matching string is stored
               in the variable.   If  the  character  immediately
               following  the ^ is a ] then it is treated as part
               of the set rather than the closing bracket for the
               set.

     The number of characters read from the input for  a  conver-
     sion is the largest number that makes sense for that partic-
     ular conversion (e.g.  as many decimal  digits  as  possible
     for %d, as many octal digits as possible for %o, and so on).
     The input field for a  given  conversion  terminates  either
     when a white-space character is encountered or when the max-
     imum field width has been reached,  whichever  comes  first.
     If  a * is present in the conversion specifier then no vari-
     able is assigned and the next scan argument is not consumed.


DIFFERENCES FROM ANSI SSCANF
     The behavior of the scan command is the same as the behavior
     of  the  ANSI  C  sscanf  procedure except for the following
     differences:

     [1]  %p and %n conversion specifiers are not currently  sup-  |
          ported.

     [2]  For %c conversions a single  character  value  is  con-
          verted  to  a decimal string, which is then assigned to
          the corresponding varName; no field width may be speci-
          fied for this conversion.

     [3]  The l, h, and L modifiers are ignored;  integer  values  |
          are  always  converted  as  if  there  were no modifier  |
          present and real values are always converted as if  the  |
          l  modifier  were present (i.e. type double is used for  |
          the internal representation).


KEYWORDS
     conversion specifier, parse, scan


FILE SCANNING COMMANDS
     These commands provide a facility to  scan  files,  matching
     lines  of the file against regular expressions and executing
     Tcl code on a match.  With this facility you can use Tcl  to
     do  the  sort  of file processing that is traditionally done
     with awk.  And since Tcl's  approach  is  more  declarative,
     some of the scripts that can be rather difficult to write in
     awk are simple to code in Tcl.

     File scanning in Tcl centers around the concept  of  a  scan
     context.   A  scan context contains one or more match state-
     ments, which associate regular expressions to scan for  with
     Tcl code to be executed when the expressions are matched.

     scancontext ?option?
          This command manages file scan contexts.  A  scan  con-
          text  is  a  collection of regular expressions and com-
          mands to execute when that regular expression matches a
          line  of  the  file.   A context may also have a single
          default match, to be applied against lines that do  not
          match  any  of  the regular expressions.  Multiple scan
          contexts may be defined and they may be reused on  mul-
          tiple files.  A scan context is identified by a context
          handle.  The scancontext command  takes  the  following
          forms:

     scancontext create
          Create a new scan context.  The  scanmatch  command  is
          used  to define patterns in the context.  A contexthan-
          dle is returned, which the Tcl programmer uses to refer
          to  the  newly created scan context in calls to the Tcl
          file scanning commands.

     scancontext delete contexthandle
          Delete the scan context  identified  by  contexthandle,
          and free all of the match statements and compiled regu-
          lar expressions associated with the specified context.

     scanfile ?-copyfile copyFileId? contexthandle fileId
          Scan the file specified by fileId,  starting  from  the
          current  file position.  Check all patterns in the scan
          context specified by contexthandle against it,  execut-
          ing   the  match  commands  corresponding  to  patterns
          matched.

          If the optional -copyfile argument  is  specified,  the
          next  argument  is  a  file  ID  to which all lines not
          matched by any pattern (excluding the default  pattern)
          are to be written.

     scanmatch ?-nocase? contexthandle ?regexp? commands
          Specify Tcl commands, to be evaluated  when  regexp  is
          matched  by  a scanfile command.  The match is added to
          the  scan  context  specified  by  contexthandle.   Any
          number  of match statements may be specified for a give
          context.  Regexp  is  a  regular  expression  (see  the
          regexp  command).  If -nocase is specified as the first
          argument, the pattern is matched regardless  of  alpha-
          betic case.

          If regexp is not specified, then  a  default  match  is
          specified for the scan context.  The default match will
          be executed when a line of the file does not match  any
          of the regular expressions in the current scancontext.

          The array matchInfo is available to the Tcl  code  that
          is  executed  when an expression matches (or defaults).
          It contans information about the file being scanned and
          where within it the expression was matched.

          matchInfo is local to the top level of the  match  com-
          mand  unless  declared  global at that level by the Tcl
          global command.  If it is to be used as  a  global,  it
          must  be  declared  global  before  scanfile  is called
          (since scanfile sets the  matchInfo  before  the  match
          code is executed, a subsequent global will override the
          local  variable).   The  following  array  entries  are
          available:

          matchInfo(line)
               Contains the text of the line of the file that was
               matched.

          matchInfo(offset)
               The byte offset into the file of the first charac-
               ter of the line that was matched.

          matchInfo(linenum)
               The line number of the line that was matched. This
               is  relative  to  the first line scanned, which is
               usually, but not necessarily, the  first  line  of
               the file.  The first line is line number one.

          matchInfo(handle)
               The file id (handle) of the file  currently  being
               scanned.

          matchInfo(copyHandle)
               The file id (handle) of the file specified by  the
               -copyfile  option.   The element does not exist if
               -copyfile was not specified.

          matchInfo(submatch0)
               Will contain the  characters  matching  the  first
               parenthesized  subexpression.   The second will be
               contained in submatch1, etc.

          matchInfo(subindex0)
               Will contain the a list of the starting and ending
               indices   of   the   string   matching  the  first
               parenthesized subexpression.  The second  will  be
               contained in subindex1, etc.

     All scanmatch patterns that match a line will  be  processed
     in the order in which their specifications were added to the
     scan context.   The  remainder  of  the  scanmatch  pattern-
     command  pairs  may be skipped for a file line if a continue
     is executed by the Tcl code of a preceding, matched pattern.

     If a return is executed in the body of  the  match  command,
     the scanfile command currently in progress returns, with the
     value passed to return as its return value.


_________________________________________________________________

NAME
     seek - Change the access position for an open file

SYNOPSIS
     seek fileId offset ?origin?
_________________________________________________________________


DESCRIPTION
     Change the current access position for fileId.  FileId  must
     have  been the return value from a previous call to open, or
     it may be stdin, stdout, or stderr to refer to  one  of  the
     standard  I/O  channels.   The  offset  and origin arguments
     specify the position at which the next read  or  write  will
     occur  for  fileId.  Offset must be an integer (which may be
     negative) and origin must be one of the following:

     start
          The new access position will be offset bytes  from  the
          start of the file.

     current
          The new access position will be offset bytes  from  the
          current  access  position;  a negative offset moves the
          access position backwards in the file.

     end  The new access position will be offset bytes  from  the
          end  of  the file.  A negative offset places the access
          position before the end-of-file, and a positive  offset
          places the access position after the end-of-file.

     The origin argument defaults to start.  This command returns
     an empty string.


KEYWORDS
     access position, file, seek


_________________________________________________________________

NAME
     set - Read and write variables

SYNOPSIS
     set varName ?value?
_________________________________________________________________


DESCRIPTION
     Returns the value of variable varName.  If value  is  speci-
     fied, then set the value of varName to value, creating a new
     variable if one doesn't already exist, and return its value.
     If  varName  contains  an  open  parenthesis and ends with a
     close parenthesis, then it refers to an array element:   the
     characters before the first open parenthesis are the name of
     the array, and the characters between  the  parentheses  are
     the  index  within the array.  Otherwise varName refers to a
     scalar variable.  If no procedure is  active,  then  varName
     refers to a global variable.  If a procedure is active, then
     varName refers to a parameter or local variable of the  pro-
     cedure unless the global command has been invoked to declare
     varName to be global.


KEYWORDS
     read, write, variable


_________________________________________________________________

NAME
     source - Evaluate a file as a Tcl script

SYNOPSIS
     source fileName
_________________________________________________________________


DESCRIPTION
     Read file fileName and pass the contents to the  Tcl  inter-
     preter  as  a script to evaluate in the normal fashion.  The
     return value from source is the return  value  of  the  last
     command  executed  from  the  file.   If  an error occurs in
     evaluating the contents of the file then the source  command
     will return that error.  If a return command is invoked from
     within the file then the  remainder  of  the  file  will  be
     skipped and the source command will return normally with the
     result from the return command.  If fileName starts  with  a
     tilde,  then  it  is  tilde-substituted  as described in the
     Tcl_TildeSubst manual entry.


KEYWORDS
     file, script


_________________________________________________________________

NAME
     split - Split a string into a proper Tcl list

SYNOPSIS
     split string ?splitChars?
_________________________________________________________________


DESCRIPTION
     Returns a list created by splitting string at each character
     that  is  in  the  splitChars argument.  Each element of the
     result list will consist of the characters from string  that
     lie  between  instances  of  the  characters  in splitChars.
     Empty list elements will be  generated  if  string  contains
     adjacent  characters  in splitChars, or if the first or last
     character of string is in splitChars.  If splitChars  is  an
     empty  string  then  each  character  of  string  becomes  a
     separate element of the result list.  SplitChars defaults to
     the standard white-space characters.  For example,

          split "comp.unix.misc" .
     returns "comp unix misc" and

          split "Hello world" {}
     returns "H e l l o { } w o r l d".


KEYWORDS
     list, split, string


_________________________________________________________________

NAME
     string - Manipulate strings

SYNOPSIS
     string option arg ?arg ...?
_________________________________________________________________


DESCRIPTION
     Performs one of  several  string  operations,  depending  on
     option.  The legal options (which may be abbreviated) are:

     string compare string1 string2
          Perform a character-by-character comparison of  strings
          string1  and  string2  in  the same way as the C strcmp
          procedure.  Return -1, 0, or 1,  depending  on  whether
          string1  is  lexicographically  less than, equal to, or
          greater than string2.

     string first string1 string2
          Search  string2  for  a  sequence  of  characters  that
          exactly  match  the  characters  in string1.  If found,
          return the index of the first character  in  the  first
          such match within string2.  If not found, return -1.

     string index string charIndex
          Returns the charIndex'th character of the string  argu-
          ment.   A charIndex of 0 corresponds to the first char-
          acter of the string.  If charIndex is less  than  0  or
          greater  than or equal to the length of the string then
          an empty string is returned.

     string last string1 string2
          Search  string2  for  a  sequence  of  characters  that
          exactly  match  the  characters  in string1.  If found,
          return the index of the first  character  in  the  last
          such  match within string2.  If there is no match, then
          return -1.

     string length string
          Returns a decimal string giving the number  of  charac-
          ters in string.

     string match pattern string
          See if pattern matches string; return 1 if it  does,  0
          if  it  doesn't.  Matching is done in a fashion similar
          to that used by the C-shell.  For the  two  strings  to
          match, their contents must be identical except that the
          following special sequences may appear in pattern:

          *         Matches any sequence of characters in string,
                    including a null string.

          ?         Matches any single character in string.

          [chars]   Matches any character in  the  set  given  by
                    chars.  If a sequence of the form x-y appears
                    in chars, then any character between x and y,
                    inclusive, will match.

          \x        Matches the single character  x.   This  pro-
                    vides a way of avoiding the special interpre-
                    tation of the characters *?[]\ in pattern.

     string range string first last
          Returns a range of consecutive characters from  string,
          starting  with  the  character whose index is first and
          ending with the character  whose  index  is  last.   An
          index of 0 refers to the first character of the string.
          Last may be end (or any abbreviation of it) to refer to
          the  last  character  of  the string.  If first is less
          than zero then it is treated as if it were zero, and if
          last  is  greater  than  or  equal to the length of the
          string then it is treated as if it were end.  If  first
          is greater than last then an empty string is returned.

     string tolower string
          Returns a value equal to string except that  all  upper
          case letters have been converted to lower case.

     string toupper string
          Returns a value equal to string except that  all  lower
          case letters have been converted to upper case.

     string trim string ?chars?
          Returns a value equal to string except that any leading
          or  trailing characters from the set given by chars are
          removed.  If chars is not specified then white space is
          removed (spaces, tabs, newlines, and carriage returns).

     string trimleft string ?chars?
          Returns a value equal to string except that any leading
          characters from the set given by chars are removed.  If
          chars is not specified  then  white  space  is  removed
          (spaces, tabs, newlines, and carriage returns).

     string trimright string ?chars?
          Returns a value equal to string except that any  trail-
          ing characters from the set given by chars are removed.
          If chars is not specified then white space  is  removed
          (spaces, tabs, newlines, and carriage returns).


KEYWORDS
     case conversion, compare, index, match, pattern, string


_________________________________________________________________

NAME
     switch - Evaluate one of several  scripts,  depending  on  a
     given value

SYNOPSIS
     switch ?options? string pattern body ?pattern body ...?
     switch ?options? string {pattern body ?pattern body ...?}
_________________________________________________________________


DESCRIPTION
     The switch command matches its string argument against  each
     of  the  pattern  arguments in order.  As soon as it finds a
     pattern that matches string it evaluates the following  body
     argument  by  passing  it recursively to the Tcl interpreter
     and returns the result of that evaluation.  If the last pat-
     tern  argument  is  default then it matches anything.  If no
     pattern argument matches string and  no  default  is  given,
     then the switch command returns an empty string.

     If the initial arguments to switch start with  -  then  they
     are treated as options.  The following options are currently
     supported:

     -exact    Use exact matching when comparing string to a pat-
               tern.  This is the default.

     -glob     When matching string to the  patterns,  use  glob-
               style  matching  (i.e.  the same as implemented by
               the string match command).

     -regexp   When matching string to the patterns, use  regular
               expression  matching (i.e. the same as implemented
               by the regexp command).

     --        Marks the end of options.  The argument  following
               this  one  will  be  treated  as string even if it
               starts with a -.

     Two syntaxes are provided for the  pattern  and  body  argu-
     ments.   The  first uses a separate argument for each of the
     patterns and commands; this form is convenient if  substitu-
     tions  are desired on some of the patterns or commands.  The
     second form places all of the patterns and commands together
     into  a  single argument; the argument must have proper list
     structure, with the elements of the list being the  patterns
     and  commands.   The  second form makes it easy to construct
     multi-line switch commands,  since  the  braces  around  the
     whole list make it unnecessary to include a backslash at the
     end of each line.  Since the pattern arguments are in braces
     in the second form, no command or variable substitutions are
     performed on them;  this makes the behavior  of  the  second
     form different than the first form in some cases.

     If a body is specified as ``-'' it means that the  body  for
     the  next  pattern  should also be used as the body for this
     pattern (if the next pattern also has a body of  ``-''  then
     the body after that is used, and so on).  This feature makes
     it possible to share a single body among several patterns.

     Below are some examples of switch commands:

          switch abc a - b {format 1} abc {format 2} default {format 3}
     will return 2,

          switch -regexp aaab {
            ^a.*b$ -
            b {format 1}
            a* {format 2}
            default {format 3}
          }
     will return 1, and

          switch xyz {
            a
              -
            b
              {format 1}
            a*
              {format 2}
            default
              {format 3}
          }
     will return 3.


KEYWORDS
     switch, match, regular expression


_________________________________________________________________

NAME
     tclvars - Variables used by Tcl
_________________________________________________________________


DESCRIPTION
     The following  global  variables  are  created  and  managed
     automatically by the Tcl library.  Except where noted below,
     these variables should normally be treated as  read-only  by
     application-specific code and by users.

     env
          This variable is maintained by Tcl as  an  array  whose
          elements are the environment variables for the process.
          Reading  an  element  will  return  the  value  of  the
          corresponding environment variable.  Setting an element
          of the array will modify the corresponding  environment
          variable  or  create  a  new  one if it doesn't already
          exist.  Unsetting an element of  env  will  remove  the
          corresponding environment variable.  Changes to the env
          array will affect the environment passed to children by
          commands  like  exec.  If the entire env array is unset
          then Tcl will stop monitoring env accesses and will not
          update environment variables.

     errorCode
          After an error has occurred, this variable will be  set
          to  hold  additional  information  about the error in a
          form that is easy to process with programs.   errorCode
          consists  of a Tcl list with one or more elements.  The
          first element of the list identifies a general class of
          errors,  and  determines  the format of the rest of the
          list.  The following formats for errorCode are used  by
          the  Tcl core; individual applications may define addi-
          tional formats.

          ARITH code msg
               This format  is  used  when  an  arithmetic  error  |
               occurs  (e.g.  an attempt to divide by zero in the  |
               expr command).  Code identifies the precise  error  |
               and  msg  provides a human-readable description of  |
               the error.  Code will be either  DIVZERO  (for  an  |
               attempt to divide by zero), DOMAIN (if an argument  |
               is outside the  domain  of  a  function,  such  as  |
               acos(-3)),   IOVERFLOW   (for  integer  overflow),  |
               OVERLFLOW (for a floating-point overflow), or UNK-  |
               NOWN  (if  the cause of the error cannot be deter-  |
               mined).

          CHILDKILLED pid sigName msg
               This format is used when a child process has  been
               killed because of a signal.  The second element of
               errorCode will be  the  process's  identifier  (in
               decimal).   The third element will be the symbolic
               name of the signal that caused the process to ter-
               minate;  it  will  be  one  of  the names from the
               include  file  signal.h,  such  as  SIGPIPE.   The
               fourth element will be a short human-readable mes-
               sage describing the signal,  such  as  ``write  on
               pipe with no readers'' for SIGPIPE.

          CHILDSTATUS pid code
               This format is  used  when  a  child  process  has
               exited  with  a  non-zero exit status.  The second
               element of errorCode will be the  process's  iden-
               tifier  (in decimal) and the third element will be
               the exit code returned by  the  process  (also  in
               decimal).

          CHILDSUSP pid sigName msg
               This format is used when a child process has  been
               suspended because of a signal.  The second element
               of errorCode will be the process's identifier,  in
               decimal.   The  third element will be the symbolic
               name of the signal  that  caused  the  process  to
               suspend;  this  will  be one of the names from the
               include  file  signal.h,  such  as  SIGTTIN.   The
               fourth element will be a short human-readable mes-
               sage describing the signal, such  as  ``background
               tty read'' for SIGTTIN.

          NONE
               This format is used for errors where no additional
               information  is available for an error besides the
               message returned with the error.  In  these  cases
               errorCode will consist of a list containing a sin-
               gle element whose contents are NONE.

          POSIX errName msg
               If the first element of errorCode is  POSIX,  then  |
               the  error  occurred  during  a POSIX kernel call.
               The second element of the list  will  contain  the
               symbolic  name of the error that occurred, such as
               ENOENT; this will be one of the values defined  in
               the  include  file  errno.h.  The third element of
               the  list  will  be   a   human-readable   message
               corresponding  to  errName, such as ``no such file
               or directory'' for the ENOENT case.

          To set errorCode, applications should use library  pro-
          cedures such as Tcl_SetErrorCode and Tcl_PosixError, or  |
          they may invoke the error command.   If  one  of  these
          methods hasn't been used, then the Tcl interpreter will
          reset the variable to NONE after the next error.

     errorInfo
          After an error has occurred, this string  will  contain
          one or more lines identifying the Tcl commands and pro-
          cedures that were being executed when the  most  recent
          error  occurred.  Its contents take the form of a stack
          trace showing the various nested Tcl commands that  had
          been invoked at the time of the error.

     tcl_precision
          If this variable is set,  it  must  contain  a  decimal  |
          number  giving  the  number  of  significant  digits to  |
          include  when  converting  floating-point   values   to  |
          strings.  If this variable is not set then 6 digits are  |
          included.  17 digits is ``perfect'' for IEEE  floating-  |
          point  in  that it allows double-precision values to be  |
          converted to strings and back to binary with no loss of  |
          precision.


KEYWORDS
     arithmetic, error, environment,  POSIX,  precision,  subpro-
     cess, variables


_________________________________________________________________

NAME
     tell - Return current access position for an open file

SYNOPSIS
     tell fileId
_________________________________________________________________


DESCRIPTION
     Returns a decimal string giving the current access  position
     in  fileId.   FileId  must have been the return value from a
     previous call to open, or it may be stdin, stdout, or stderr
     to refer to one of the standard I/O channels.


KEYWORDS
     access position, file


_________________________________________________________________

NAME
     time - Time the execution of a script

SYNOPSIS
     time script ?count?
_________________________________________________________________


DESCRIPTION
     This command will call the Tcl interpreter  count  times  to
     evaluate script (or once if count isn't specified).  It will
     then return a string of the form

          503 microseconds per iteration
     which indicates the average  amount  of  time  required  per
     iteration,  in  microseconds.   Time  is measured in elapsed
     time, not CPU time.


KEYWORDS
     script, time


_________________________________________________________________

NAME
     trace - Monitor variable accesses

SYNOPSIS
     trace option ?arg arg ...?
_________________________________________________________________


DESCRIPTION
     This command causes Tcl commands  to  be  executed  whenever
     certain  operations  are invoked.  At present, only variable
     tracing is implemented. The legal  option's  (which  may  be
     abbreviated) are:

     trace variable name ops command
          Arrange for command to be  executed  whenever  variable
          name is accessed in one of the ways given by ops.  Name
          may refer to a normal variable, an element of an array,
          or  to  an  array as a whole (i.e. name may be just the
          name of an array, with  no  parenthesized  index).   If
          name  refers  to a whole array, then command is invoked
          whenever any element of the array is manipulated.

          Ops indicates which operations  are  of  interest,  and
          consists of one or more of the following letters:

               r    Invoke command whenever the variable is read.

               w    Invoke command whenever the variable is writ-
                    ten.

               u    Invoke  command  whenever  the  variable   is
                    unset.   Variables  can  be  unset explicitly
                    with the unset command,  or  implicitly  when
                    procedures  return  (all of their local vari-
                    ables are unset).  Variables are  also  unset
                    when  interpreters  are  deleted,  but traces
                    will not  be  invoked  because  there  is  no
                    interpreter in which to execute them.

          When the trace triggers, three arguments  are  appended
          to command so that the actual command is as follows:

               command name1 name2 op
          Name1 and name2 give the name(s) for the variable being
          accessed:  if the variable is a scalar then name1 gives
          the variable's name and name2 is an  empty  string;  if
          the  variable  is an array element then name1 gives the
          name of the array and name2 gives the  index  into  the
          array;  if  an  entire  array  is being deleted and the
          trace was registered on the overall array, rather  than
          a  single  element, then name1 gives the array name and
          name2 is an empty string.  Op indicates what  operation
          is being performed on the variable, and is one of r, w,
          or u as defined above.

          Command executes in the same context as the  code  that
          invoked  the  traced  operation:   if  the variable was
          accessed as part of a Tcl procedure, then command  will
          have  access to the same local variables as code in the
          procedure.  This context may be different than the con-
          text  in  which  the  trace  was  created.   If command
          invokes a procedure (which it normally does)  then  the
          procedure  will  have  to  use  upvar  or uplevel if it
          wishes to access the traced variable.  Note  also  that
          name1  may not necessarily be the same as the name used
          to set the trace  on  the  variable;   differences  can
          occur  if the access is made through a variable defined
          with the upvar command.

          For read and write traces, command can modify the vari-
          able  to affect the result of the traced operation.  If
          command modifies the value of a variable during a  read
          or  write trace, then the new value will be returned as
          the result of the traced operation.  The  return  value
          from   command  is ignored except that if it returns an
          error of  any  sort  then  the  traced  operation  also
          returns  an  error with the same error message returned  |
          by the trace command (this mechanism  can  be  used  to
          implement read-only variables, for example).  For write
          traces, command is invoked after the  variable's  value
          has  been  changed;  it  can write a new value into the
          variable to override the original  value  specified  in
          the write operation.  To implement read-only variables,
          command will have to restore the old value of the vari-
          able.

          While command is  executing  during  a  read  or  write
          trace, traces on the variable are temporarily disabled.
          This means that reads and  writes  invoked  by  command
          will  occur  directly, without invoking command (or any
          other traces) again.  However, if  command  unsets  the  |
          variable then unset traces will be invoked.

          When an  unset  trace  is  invoked,  the  variable  has
          already  been  deleted:  it will appear to be undefined
          with no traces.  If an unset occurs because of  a  pro-
          cedure  return,  then  the trace will be invoked in the
          variable context of the procedure  being  returned  to:
          the  stack  frame  of  the  returning procedure will no
          longer exist.  Traces are  not  disabled  during  unset
          traces,  so  if  an  unset  trace command creates a new
          trace and accesses the  variable,  the  trace  will  be
          invoked.  Any errors in unset traces are ignored.        |

          If there are multiple traces on  a  variable  they  are
          invoked  in  order  of creation, most-recent first.  If
          one trace returns an error, then no further traces  are
          invoked  for  the  variable.  If an array element has a
          trace set, and there is also a trace set on  the  array
          as  a  whole, the trace on the overall array is invoked
          before the one on the element.

          Once created, the trace remains in effect either  until
          the  trace  is  removed  with the trace vdelete command
          described below, until the variable is unset, or  until
          the  interpreter  is  deleted.  Unsetting an element of
          array will remove any traces on that element, but  will
          not remove traces on the overall array.

          This command returns an empty string.

     trace vdelete name ops command
          If there is a trace  set  on  variable  name  with  the
          operations  and  command given by ops and command, then
          the trace is removed, so that command will never  again
          be invoked.  Returns an empty string.

     trace vinfo name
          Returns a list containing one element  for  each  trace
          currently  set  on  variable name.  Each element of the
          list is itself a list containing  two  elements,  which
          are  the ops and command associated with the trace.  If
          name doesn't exist or doesn't have any traces set, then
          the result of the command will be an empty string.


KEYWORDS
     read, variable, write, trace, unset


_________________________________________________________________

NAME
     unknown - Handle attempts to use non-existent commands

SYNOPSIS
     unknown cmdName ?arg arg ...?
_________________________________________________________________


DESCRIPTION
     This command doesn't actually exist as part of Tcl, but  Tcl
     will  invoke  it  if  it does exist.  If the Tcl interpreter
     encounters a command name for which there is not  a  defined
     command,  then  Tcl  checks  for  the existence of a command
     named unknown.  If there is no such command, then the inter-
     preter  returns  an  error.   If the unknown command exists,
     then it is invoked with arguments consisting of  the  fully-
     substituted name and arguments for the original non-existent
     command.  The unknown command  typically  does  things  like
     searching  through  library  directories  for a command pro-
     cedure with the name cmdName, or expanding abbreviated  com-
     mand  names  to full-length, or automatically executing unk-
     nown commands as sub-processes.   In  some  cases  (such  as
     expanding  abbreviations)  unknown  will change the original
     command slightly and then (re-)execute it.   The  result  of
     the  unknown  command is used as the result for the original
     non-existent command.


KEYWORDS
     error, non-existent command


_________________________________________________________________

NAME
     unset - Delete variables

SYNOPSIS
     unset name ?name name ...?
_________________________________________________________________


DESCRIPTION
     This command removes one or more variables.  Each name is  a
     variable  name,  specified  in any of the ways acceptable to
     the set command.  If a name refers to an element of an array
     then  that  element is removed without affecting the rest of
     the array.  If a name consists of  an  array  name  with  no
     parenthesized  index, then the entire array is deleted.  The
     unset command returns an empty string as result.   An  error
     occurs  if any of the variables doesn't exist, and any vari-
     ables after the non-existent one are not deleted.


KEYWORDS
     remove, variable


_________________________________________________________________

NAME
     uplevel - Execute a script in a different stack frame

SYNOPSIS
     uplevel ?level? arg ?arg ...?
_________________________________________________________________


DESCRIPTION
     All of the arg arguments are concatenated  as  if  they  had
     been  passed  to concat; the result is then evaluated in the
     variable context indicated by level.   Uplevel  returns  the
     result of that evaluation.

     If level is an integer then it gives a distance (up the pro-
     cedure  calling stack) to move before executing the command.
     If level consists of # followed by a number then the  number
     gives an absolute level number.  If level is omitted then it
     defaults to 1.  Level cannot be defaulted if the first  com-
     mand argument starts with a digit or #.

     For example, suppose that procedure a was invoked from  top-
     level,  and  that it called b, and that b called c.  Suppose
     that c invokes the uplevel command.  If level is 1 or #2  or
     omitted,  then  the command will be executed in the variable
     context of b.  If level is 2 or #1 then the command will  be
     executed  in the variable context of a.  If level is 3 or #0
     then the command will be executed at top-level (only  global
     variables will be visible).

     The uplevel command causes the invoking procedure to  disap-
     pear  from  the procedure calling stack while the command is
     being executed.  In the above example, suppose c invokes the
     command

          uplevel 1 {set x 43; d}
     where d is another Tcl  procedure.   The  set  command  will
     modify  the variable x in b's context, and d will execute at
     level 3, as if called from b.  If it in  turn  executes  the
     command

          uplevel {set x 42}
     then the set command will modify the same variable x in  b's
     context:   the procedure c does not appear to be on the call
     stack when d is executing.  The command ``info  level''  may
     be used to obtain the level of the current procedure.

     Uplevel makes it possible  to  implement  new  control  con-
     structs  as  Tcl  procedures  (for example, uplevel could be
     used to implement the while construct as a Tcl procedure).


KEYWORDS
     context, stack frame, variables


_________________________________________________________________

NAME
     upvar - Create link to variable in a different stack frame

SYNOPSIS
     upvar ?level? otherVar myVar ?otherVar myVar ...?
_________________________________________________________________


DESCRIPTION
     This command arranges for one or more local variables in the
     current procedure to refer to variables in an enclosing pro-
     cedure call or to global variables.  Level may have  any  of
     the  forms  permitted  for  the  uplevel command, and may be
     omitted if the first letter of the first otherVar isn't # or
     a  digit  (it  defaults  to 1).  For each otherVar argument,
     upvar makes the variable by that name in the procedure frame
     given by level (or at global level, if level is #0) accessi-
     ble in the current  procedure  by  the  name  given  in  the
     corresponding  myVar argument.  The variable named by other-
     Var need not exist at the time of  the  call;   it  will  be
     created  the  first  time  myVar is referenced, just like an
     ordinary variable.  Upvar may only be  invoked  from  within
     procedures.   MyVar may not refer to an element of an array,  |
     but otherVar may refer to an array element.   Upvar  returns
     an empty string.

     The upvar command simplifies the implementation of  call-by-
     name procedure calling and also makes it easier to build new
     control constructs as Tcl procedures.  For example, consider
     the following procedure:

          proc add2 name {
              upvar $name x
              set x [expr $x+2]
          }
     Add2 is invoked with an argument giving the name of a  vari-
     able,  and  it  adds  two  to  the  value  of that variable.
     Although add2 could  have  been  implemented  using  uplevel
     instead  of upvar, upvar makes it simpler for add2 to access
     the variable in the caller's procedure frame.

     If an upvar variable is unset (e.g. x in  add2  above),  the  |
     unset  operation  affects  the variable it is linked to, not  |
     the upvar variable.  There is no way to unset an upvar vari-  |
     able except by exiting the procedure in which it is defined.  |
     However, it is possible to retarget  an  upvar  variable  by  |
     executing another upvar command.


KEYWORDS
     context, frame, global, level, procedure, variable


_________________________________________________________________

NAME
     while - Execute script repeatedly as long as a condition  is
     met

SYNOPSIS
     while test body
_________________________________________________________________


DESCRIPTION
     The while command evaluates test as an  expression  (in  the
     same  way  that  expr evaluates its argument).  The value of
     the expression must a proper boolean value; if it is a  true
     value  then body is executed by passing it to the Tcl inter-
     preter.  Once body has been executed then test is  evaluated
     again,  and the process repeats until eventually test evalu-
     ates to a false boolean value.   Continue  commands  may  be
     executed  inside  body to terminate the current iteration of
     the loop, and break commands may be executed inside body  to
     cause immediate termination of the while command.  The while
     command always returns an empty string.


KEYWORDS
     boolean value, loop, test, while


